Difference between revisions of "RCauth.eu and MasterPortal VOPortal integration guide"

From PDP/Grid Wiki
Jump to navigationJump to search
 
(13 intermediate revisions by the same user not shown)
Line 6: Line 6:
  
 
= Integration Workflow =
 
= Integration Workflow =
=== Register a new client ===
+
== Register a new client ==
 
Register a new client at a Master Portal at the ''/register'' endpoint:
 
Register a new client at a Master Portal at the ''/register'' endpoint:
 
<ul><li>E.g. for the EGI development instance:<br>
 
<ul><li>E.g. for the EGI development instance:<br>
Line 15: Line 15:
 
'''''NOTE''''': Make sure to store the ''client_id'' and ''client_secret'' in a secure place.
 
'''''NOTE''''': Make sure to store the ''client_id'' and ''client_secret'' in a secure place.
  
=== Get the client approved ===
+
Newer MasterPortals (v0.2.0 and up) have on the registration form a list of allowed scopes for the new client. Choose at least the ''openid'' scope.
 +
In case the VO portal will require proxy certificates, also request the ''edu.uiuc.ncsa.myproxy.getcert'' scope.
 +
Additionally, those MasterPortals also have a checkbox for limited proxies. This is useful if the VO portal '''''only''''' uses the proxy certificates for data access, not for compute resources. When in doubt leave the box unchecked.
 +
 
 +
== Get the client approved ==
 
In order to get the client approved, send an email to the adminstrator of the Master Portal to request client approval. For EGI use [mailto:egi-aai-checkin@lists.grnet.gr EGI CheckIn support].
 
In order to get the client approved, send an email to the adminstrator of the Master Portal to request client approval. For EGI use [mailto:egi-aai-checkin@lists.grnet.gr EGI CheckIn support].
  
Line 21: Line 25:
  
 
==== Demonstrator code ====
 
==== Demonstrator code ====
See this [https://rcdemo.nikhef.nl/demobasic/oidc_getproxy_demo_source.php working PHP demo].
+
See this [https://rcdemo.nikhef.nl/demobasic/ working PHP demo with source code].
  
 
==== Implementation steps ====
 
==== Implementation steps ====
The steps needed to obtain a proxy certificate from the RCauth.eu CA via the Master Portal follow the standard OIDC Authorization Flow. The first few steps follow the generic [http://goo.gl/VnMKXS OAuth for MyProxy protocol], the last step in the Master Portal specific [[OAuth for MyProxy GetProxy Endpoint]]:
+
The steps needed to obtain a proxy certificate from the RCauth.eu CA via the Master Portal follow the standard [https://openid.net/specs/openid-connect-core-1_0.html#CodeFlowSteps OIDC Authorization Code Flow].
 +
 
 +
The first steps (1-5) also follow the generic [http://goo.gl/VnMKXS OAuth for MyProxy protocol], the last step (6/7) uses the Master Portal specific [[OAuth for MyProxy GetProxy Endpoint]]:
 
<ol>
 
<ol>
<li> VO portal initiates the flow by sending the user (browser redirect) to the ''/authorize'' endpoint on the Master Portal. Parameters (see [http://goo.gl/VnMKXS#h.cfm05rlw4qy3 Client Requests Authorization]):
+
<li> VO portal initiates the flow by sending the user (browser redirect) to the ''/authorize'' endpoint on the Master Portal.<br>
 +
Parameters (see [http://goo.gl/VnMKXS#h.cfm05rlw4qy3 Client Requests Authorization]):
 
* ''client_id=...''
 
* ''client_id=...''
 
* ''response_type=code''
 
* ''response_type=code''
Line 33: Line 40:
 
* ''scope="openid edu.uiuc.ncsa.myproxy.getcert" <br>
 
* ''scope="openid edu.uiuc.ncsa.myproxy.getcert" <br>
 
The scope ''edu.uiuc.ncsa.myproxy.getcert'' is needed for obtaining proxy certificates.<br>
 
The scope ''edu.uiuc.ncsa.myproxy.getcert'' is needed for obtaining proxy certificates.<br>
Optionally the VO portal can redirect the user to a specific IdP by also sending an ''idphint'' parameter. This is a RCauth / MasterPortal extension (see also [[Master Portal Internals#The_IdP_Hint]]).
+
Optionally the VO portal can redirect the user to a specific IdP by also sending an ''idphint'' parameter. This is an RCauth / MasterPortal extension (see also [[Master Portal Internals#The_IdP_Hint]]).
 
* ''idphint=...'' (fill in URL-encoded entityID of the IdP).
 
* ''idphint=...'' (fill in URL-encoded entityID of the IdP).
<li> When the authorization flow succeeds, an authorization grant is sent as ''code'' parameter to the ''redirect_uri'' (see [http://goo.gl/VnMKXS#h.6wef7vutcx9v Authorization Response]).
+
<li> When the authorization flow succeeds, an authorization grant is sent via the browser as ''code'' parameter to the ''redirect_uri'' (see [http://goo.gl/VnMKXS#h.6wef7vutcx9v Authorization Response]).
<li> The VO portal uses the authorization grant to obtain an ''access_token'', an ''id_token'' and optionally a ''refresh_token'' from the ''/token'' endpoint. Parameters (see [http://goo.gl/VnMKXS#h.nq5705wuugqx Access Token Request]):
+
<li> The VO portal uses the authorization grant to obtain an ''access_token'', an ''id_token'' and optionally a ''refresh_token'' from the ''/token'' endpoint (back-channel to the OIDC provider). Parameters (see [http://goo.gl/VnMKXS#h.nq5705wuugqx Access Token Request]):
 
* ''client_id=...''
 
* ''client_id=...''
 
* ''client_secret=...''
 
* ''client_secret=...''
Line 42: Line 49:
 
* ''code=...'' (fill in URL-encoded value of the code received)
 
* ''code=...'' (fill in URL-encoded value of the code received)
 
* ''redirect_uri=...''
 
* ''redirect_uri=...''
<li> When successful, the response is a JSON including the ''access_token'', ''id_token'' (and the ''refresh_token'' when configured). (see [http://goo.gl/VnMKXS#h.vanmego4hb64 Access Token Response])
+
<li> When successful, the response is a JSON including the ''access_token'', ''id_token'' (and the ''refresh_token'' when configured). (see [http://goo.gl/VnMKXS#h.vanmego4hb64 Access Token Response]).<br>
<li> The VO portal can optionally access the ''/userinfo'' endpoint using the ''access_token''. Note that it can get the same information also from the ''id_token''. Parameters (see [http://goo.gl/VnMKXS#h.ndq4whgq53o6 UserInfo Request]):
+
'''''NOTE''''': versions before v0.2.0 of the MasterPortal return the lifetime of the refresh token in the ''expires_in'' parameter of the access token response. This is a mistake in the [http://goo.gl/VnMKXS#h.vanmego4hb64 OAuth for MyProxy protocol]. V0.2.0 returns in the ''expires_in'' parameter the lifetime of the access token while in the ''refresh_token_expires_in'' parameter it return the lifetime of the refresh token.
 +
<li> The VO portal can optionally access the ''/userinfo'' endpoint using the ''access_token'' (back-channel to the OIDC provider). Note that it can get the same information directly from the ''id_token''. Parameters (see [http://goo.gl/VnMKXS#h.ndq4whgq53o6 UserInfo Request]):
 
* ''access_token=...''
 
* ''access_token=...''
<li> The VO portal can now obtain a proxy certificate from the ''/getproxy'' endpoint using the ''access_token'', and authenticating using its ''client_id'' and ''client_secret''. Parameters (see [[OAuth for MyProxy GetProxy Endpoint]]):
+
'''''NOTE''''': one of the returned claims, ''cert_subject_dn'', contains the user's DN in RFC2253 format.
 +
<li> The VO portal can now obtain a proxy certificate from the ''/getproxy'' endpoint using the ''access_token'', and authenticating using its ''client_id'' and ''client_secret'' (back-channel).<br>
 +
Parameters (see [[OAuth for MyProxy GetProxy Endpoint]]):
 
* ''client_id=...''
 
* ''client_id=...''
 
* ''client_secret=...''
 
* ''client_secret=...''
Line 56: Line 66:
 
<li> The response will consist of the proxy certificate chain in a single PEM.
 
<li> The response will consist of the proxy certificate chain in a single PEM.
 
</ol>
 
</ol>
 +
'''''NOTE''''': once an access token has been used to request a proxy certificate, the access token is no longer valid. Hence if one want to request both the userinfo and a proxy certificate, the userinfo needs to be requested first.
  
=== Security considerations ===
+
== Security considerations ==
A VO portal should make sure to store the retrieved proxy certificates in a appropriate way, such as keeping the files outside of the web root, restricting access to the host, etc.
+
A VO portal should make sure to store the retrieved proxy certificates in an appropriate way, this includes keeping the files outside of the web root, restricting access to the host, etc.
  
=== Use of the retrieved proxy certificates ===
+
== Use of the retrieved proxy certificates ==
In order to be able to use the proxy certificates, the VO portal will need to install the relevant RCauth CA files:
+
In order to be able to use the proxy certificates, the VO portal will need to install the relevant RCauth CAs:
 
* ca_RCauth-Pilot-ICA-G1
 
* ca_RCauth-Pilot-ICA-G1
 
* ca_DCAROOT-G1
 
* ca_DCAROOT-G1
 +
e.g. by installing the ca_policy_igtf-iota or ca-policy-egi-cam packages.

Latest revision as of 12:39, 4 September 2019

Overview

This page describes the steps for a VO portal or Science Gateway to obtain proxy certificates from the RCauth.eu online CA.

Note that VO portals do not directly contact the RCauth CA, but use an intermediate service, a so-called Master Portal, which handles most of the complexity. From the point of view of a VO portal, a Master Portal is an OpenID Connect Provider, with an integrated protected endpoint for obtaining proxy certificates.

Integration Workflow

Register a new client

Register a new client at a Master Portal at the /register endpoint:

NOTE: Make sure to store the client_id and client_secret in a secure place.

Newer MasterPortals (v0.2.0 and up) have on the registration form a list of allowed scopes for the new client. Choose at least the openid scope. In case the VO portal will require proxy certificates, also request the edu.uiuc.ncsa.myproxy.getcert scope. Additionally, those MasterPortals also have a checkbox for limited proxies. This is useful if the VO portal only uses the proxy certificates for data access, not for compute resources. When in doubt leave the box unchecked.

Get the client approved

In order to get the client approved, send an email to the adminstrator of the Master Portal to request client approval. For EGI use EGI CheckIn support.

Implement an OIDC Connect flow to obtain a proxy chain

Demonstrator code

See this working PHP demo with source code.

Implementation steps

The steps needed to obtain a proxy certificate from the RCauth.eu CA via the Master Portal follow the standard OIDC Authorization Code Flow.

The first steps (1-5) also follow the generic OAuth for MyProxy protocol, the last step (6/7) uses the Master Portal specific OAuth for MyProxy GetProxy Endpoint:

  1. VO portal initiates the flow by sending the user (browser redirect) to the /authorize endpoint on the Master Portal.
    Parameters (see Client Requests Authorization):
    • client_id=...
    • response_type=code
    • redirect_uri=...
    • state=...
    • scope="openid edu.uiuc.ncsa.myproxy.getcert"
    The scope edu.uiuc.ncsa.myproxy.getcert is needed for obtaining proxy certificates.
    Optionally the VO portal can redirect the user to a specific IdP by also sending an idphint parameter. This is an RCauth / MasterPortal extension (see also Master Portal Internals#The_IdP_Hint).
    • idphint=... (fill in URL-encoded entityID of the IdP).
  2. When the authorization flow succeeds, an authorization grant is sent via the browser as code parameter to the redirect_uri (see Authorization Response).
  3. The VO portal uses the authorization grant to obtain an access_token, an id_token and optionally a refresh_token from the /token endpoint (back-channel to the OIDC provider). Parameters (see Access Token Request):
    • client_id=...
    • client_secret=...
    • grant_type=authorization_code
    • code=... (fill in URL-encoded value of the code received)
    • redirect_uri=...
  4. When successful, the response is a JSON including the access_token, id_token (and the refresh_token when configured). (see Access Token Response).
    NOTE: versions before v0.2.0 of the MasterPortal return the lifetime of the refresh token in the expires_in parameter of the access token response. This is a mistake in the OAuth for MyProxy protocol. V0.2.0 returns in the expires_in parameter the lifetime of the access token while in the refresh_token_expires_in parameter it return the lifetime of the refresh token.
  5. The VO portal can optionally access the /userinfo endpoint using the access_token (back-channel to the OIDC provider). Note that it can get the same information directly from the id_token. Parameters (see UserInfo Request):
    • access_token=...
    NOTE: one of the returned claims, cert_subject_dn, contains the user's DN in RFC2253 format.
  6. The VO portal can now obtain a proxy certificate from the /getproxy endpoint using the access_token, and authenticating using its client_id and client_secret (back-channel).
    Parameters (see OAuth for MyProxy GetProxy Endpoint):
    • client_id=...
    • client_secret=...
    • access_token=...
    Optionally, it can also requested a proxy lifetime, in seconds, to override the default set on the server (typically 12 hours):
    • proxylifetime=...
    and the name of a VO plus optionally vomses information (the latter is needed unless the VO is configured on the Master Portal):
    • voms=... (e.g. testvo or testvo:/testvo/Role=VO-Admin)
    • vomses=... (e.g. the URL-encoded value of '"testvo" "vomsserver.example.org" "15000" "/C=NL/O=Example/OU=Test/CN=vomsserver.example.org" "testvo"')
  7. The response will consist of the proxy certificate chain in a single PEM.

NOTE: once an access token has been used to request a proxy certificate, the access token is no longer valid. Hence if one want to request both the userinfo and a proxy certificate, the userinfo needs to be requested first.

Security considerations

A VO portal should make sure to store the retrieved proxy certificates in an appropriate way, this includes keeping the files outside of the web root, restricting access to the host, etc.

Use of the retrieved proxy certificates

In order to be able to use the proxy certificates, the VO portal will need to install the relevant RCauth CAs:

  • ca_RCauth-Pilot-ICA-G1
  • ca_DCAROOT-G1

e.g. by installing the ca_policy_igtf-iota or ca-policy-egi-cam packages.