Difference between revisions of "Master Portal Internals"

From PDP/Grid Wiki
Jump to navigationJump to search
(authN flow image)
 
(31 intermediate revisions by 2 users not shown)
Line 1: Line 1:
The Master Portal stands at the heart of the [[CILogon Pre-Pilot Work]]. The Master Portal caches long lived user proxies into its MyProxy Crendential Store, and returns short lived proxies on demand for authenticated users via the VO Portal.  
+
The Master Portal stands at the heart of the [[RCauth.eu_and_MasterPortal_overview | RCauth and MasterPortal setup]]. The Master Portal caches long lived user proxies into its MyProxy Crendential Store, and returns short lived proxies on demand for authenticated users via the VO Portal.  
  
 
== Structure ==
 
== Structure ==
  
The Master Portal is made up internally of a [http://grid.ncsa.illinois.edu/myproxy/oauth/ OA4MP] Server and Client. For the purpose of the VO Portal, the Master Portal is an OA4MP Server. For the purpose of the Delegation Service the Master Portal is an OA4MP Client. The motivation for having OA4MP Client and Server rolled into one unit was to have a mediator between the VO Portal and the Delegation Server (Online CA), caching user credentials (long lived proxies) passing through it.
+
The Master Portal is made up internally of both an [http://grid.ncsa.illinois.edu/myproxy/oauth/ OA4MP] Server and Client. For the purpose of the VO Portal, the Master Portal is an OA4MP Server. For the purpose of the Delegation Service the Master Portal is an OA4MP Client. The motivation for having OA4MP Client and Server rolled into one unit was to have a mediator between the VO Portal and the Delegation Server (Online CA), caching user credentials (long lived proxies) passing through it, while also hiding all the complexity for the VO portals.
  
 
[[File:Masterportal-structure.svg | 600px]]
 
[[File:Masterportal-structure.svg | 600px]]
  
Most of the endpoints in the above diagram are part of the standard [https://docs.google.com/document/d/1cs3peO9FxA81KN-1RC6Z-auEFIwRbJpZ-SFuKbQzS50/pub OIDC/OA4MP protocol]. The new endpoints are marked with blue:
+
Most of the endpoints in the above diagram are part of the standard [http://goo.gl/VnMKXS OIDC/OA4MP protocol]. The new endpoints are marked with blue:
  
* /getproxy : retrieves voms proxies via the [[OAuth for MyProxy GetProxy Endpoint | GetProxy Endpoint]].
+
* /getproxy : retrieves (VOMS) proxies via the [[OAuth for MyProxy GetProxy Endpoint | GetProxy Endpoint]], see also its [[OAuth for MyProxy GetProxy Endpoint - Implementation | implementation]].
 
* /forwardgetcert : simply forwards the call to the GetCert Endpoint.
 
* /forwardgetcert : simply forwards the call to the GetCert Endpoint.
  
The '''Master Portal (OA4MP Server)''' takes registrations from VO Portals. Once a VO Portal is registered and approved, it can use the Master Portal (OA4MP Server) exposed endpoint in order to start an OIDC/OA4MP flow(1) between VO Portal and Master Portal. The only deviation from the original flow is that at the end, instead of calling the GetCert Endpoint, the VO Portal calls the [[OAuth for MyProxy GetProxy Endpoint | GetProxy Endpoint]].
+
The '''Master Portal (OA4MP Server)''' takes registrations from VO Portals. Once a VO Portal is registered and approved, it can use the Master Portal (OA4MP Server) exposed endpoint in order to start an OIDC/OA4MP flow(1) between VO Portal and Master Portal. The only deviation from the original flow is that here, instead of calling the GetCert Endpoint, the VO Portal calls the [[OAuth for MyProxy GetProxy Endpoint | GetProxy Endpoint]] in the last step.
  
The '''Master Portal (OA4MP Client)''' component has to be registered with the Delegation Server (OA4MP Server). It starts a second OIDC/OA4MP flow(2) between Master Portal and Delegation Server. Here, the GetCert Endpoint is left unchanged.
+
The '''Master Portal (OA4MP Client)''' component has to be registered as client with the Delegation Server (OA4MP Server). It starts a second OIDC/OA4MP flow(2) between Master Portal and Delegation Server. In this second flow, the last step, involving the GetCert Endpoint, is left unchanged.
  
 
The two components will interact for the following reasons:  
 
The two components will interact for the following reasons:  
  
* User Authentication : the Master Portal is not configured to authenticate users, therefore user authentication requests have to be forwarded to the Delegation Server. On the diagram the /startRequest and /authorize calls serve this purpose.
+
* User Authentication : the Master Portal is not configured to authenticate users directly, instead user authentication requests are forwarded to the Delegation Server. In the diagram the /startRequest and /authorize calls serve this purpose.
* Certificate Requests : the Master Portal cannot issue '''new credentials''' for authenticated users, it can only retrieve credentials for users who already have a valid credential in the MyProxy Credential Store. Asking for a '''new credential''' (either for new users, or users who's credential expired in the credential store) can be done by calling the GetCert Endpoint. The /forwardgetcert is used for this.
+
* Certificate Requests : the Master Portal cannot issue '''new credentials''' for authenticated users, it can only retrieve credentials for users who already have a valid credential in the MyProxy Credential Store. Asking for a '''new credential''' (either for new users, or users who's credential expired in the credential store) can be done by calling a GetCert Endpoint. The /forwardgetcert is used for this.
  
 
== Authentication Flow ==
 
== Authentication Flow ==
Line 33: Line 33:
 
<ol>
 
<ol>
 
<li>The VO Portal starts an OIDC/OA4MP flow by sending an authorization request to the Master Portal (OA4MP Server).</li>
 
<li>The VO Portal starts an OIDC/OA4MP flow by sending an authorization request to the Master Portal (OA4MP Server).</li>
<li>According to the [http://grid.ncsa.illinois.edu/myproxy/oauth/server/manuals/authorized.xhtml OA4MP mini-protocol], a call to /authorize'''d''' endpoint is made to retrieve the '''code''' & '''state''' of the initiated transaction.</li>
+
<li>According to the [http://grid.ncsa.illinois.edu/myproxy/oauth/server/manuals/authorized.xhtml OA4MP mini-protocol], a call to the /authorize'''d''' endpoint is made to retrieve the '''code''' & '''state''' of the initiated transaction.</li>
<li>The authN request forwarding is done by triggering a second OIDC/OA4MP flow between the Master Portal (OA4MP Client) and the Delegation Service. The /startRequest endpoint will kick this second flow off.</li>
+
<li>The authN request forwarding is done by triggering a second OIDC/OA4MP flow between the Master Portal (OA4MP Client) and the Delegation Service. The /startRequest endpoint will kick off this second flow.</li>
 
<ol style="list-style-type:square">
 
<ol style="list-style-type:square">
 
<li>The '''code''' & '''state''' are sent from the Master Portal (OA4MP Server) to the Master Portal (OA4MP Client) for session keeping.</li>
 
<li>The '''code''' & '''state''' are sent from the Master Portal (OA4MP Server) to the Master Portal (OA4MP Client) for session keeping.</li>
 
</ol>
 
</ol>
<li>The Master Portal (OA4MP Client) starts the second OIDC/OA4MP flow by sending an authorization request to the Delegation Server</li>
+
<li>The Master Portal (OA4MP Client) starts the second OIDC/OA4MP flow by sending an authorization request to the Delegation Server.</li>
 
<ol style="list-style-type:square">
 
<ol style="list-style-type:square">
 
<li>The '''identifier''' is send along in a cookie. This is used to keep session between the user (browser) and the Master Portal (OA4MP Client).</li>
 
<li>The '''identifier''' is send along in a cookie. This is used to keep session between the user (browser) and the Master Portal (OA4MP Client).</li>
 
</ol>
 
</ol>
<li>In case the user is correctly authenticated, the Delegation Server will trigger a browser redirect to the ''redirect_uri'' (/ready endpoint) on the Master Portal (OA4MP Client). This endpoint has to be pre-registered with the Delegation Server!</li>
+
<li>When the user is correctly authenticated, the Delegation Server will trigger a browser redirect to the ''redirect_uri'' (/ready endpoint) on the Master Portal (OA4MP Client). This endpoint has to be pre-registered with the Delegation Server!</li>
 
<ol style="list-style-type:square">
 
<ol style="list-style-type:square">
 
<li>The '''identifier''' (from step a.4) is extracted from the cookies in order to identify the pending authN session of Master Portal (OA4MP Client).</li>
 
<li>The '''identifier''' (from step a.4) is extracted from the cookies in order to identify the pending authN session of Master Portal (OA4MP Client).</li>
 
</ol>
 
</ol>
<li>The Master Portal (OA4MP Client) retrieves an Access Token from the Delegation Server</li>
+
<li>The Master Portal (OA4MP Client) retrieves an Access Token from the Delegation Server.</li>
 
<li>The Master Portal (OA4MP Client) retrieves information of the authenticated user from the Delegation Server. This includes the '''username'''.</li>
 
<li>The Master Portal (OA4MP Client) retrieves information of the authenticated user from the Delegation Server. This includes the '''username'''.</li>
 
</ol>
 
</ol>
Line 55: Line 55:
 
<li>The '''code''' & '''state''' (received in step a.3) are also send back in order to identify the pending authN session of Master Portal (OA4MP Server).</li>
 
<li>The '''code''' & '''state''' (received in step a.3) are also send back in order to identify the pending authN session of Master Portal (OA4MP Server).</li>
 
</ol>
 
</ol>
<li>The Master Portal (OA4MP Server) answers to the authorization requests from step a.1</li>
+
<li>The Master Portal (OA4MP Server) answers to the authorization requests from step a.1.</li>
 
</ol>
 
</ol>
 
</ol>
 
</ol>
Line 61: Line 61:
 
=== Endpoints ===
 
=== Endpoints ===
  
Both Master Portal components expose a set of endpoint, however some of these endpoints are only meant to be called internally. Make sure to restrict access to internal endpoints!  
+
Both Master Portal components expose a set of endpoints, however some of these endpoints are only meant to be called internally. Make sure to restrict access to internal endpoints!  
  
 
The Master Portal (OA4MP Server) hosts most of the forward facing endpoints:
 
The Master Portal (OA4MP Server) hosts most of the forward facing endpoints:
Line 70: Line 70:
 
| style="width: 15%;" | Exposed  
 
| style="width: 15%;" | Exposed  
 
| Description
 
| Description
 +
 +
|-
 +
| style="width: 25%;" | /register
 +
| style="width: 15%;" | Y
 +
| Client Registration Endpoint
  
 
|-
 
|-
Line 90: Line 95:
 
| style="width: 15%;" | Y  
 
| style="width: 15%;" | Y  
 
| Userinfo Endpoint
 
| Userinfo Endpoint
 +
 +
|-
 +
| style="width: 25%;" | /.well-known/openid-configuration
 +
| style="width: 15%;" | Y
 +
| well-known openid configuration Endpoint
  
 
|-
 
|-
 
| style="width: 25%;" | /getproxy
 
| style="width: 25%;" | /getproxy
 
| style="width: 15%;" | Y  
 
| style="width: 15%;" | Y  
| [[OAuth for MyProxy GetProxy Endpoint | GetProxy Endpoint]]
+
| [[OAuth for MyProxy GetProxy Endpoint | GetProxy Endpoint]], see also its [[OAuth for MyProxy GetProxy Endpoint - Implementation | implementation]]
 +
 
 +
|-
 +
| style="width: 25%;" | /sshkey
 +
| style="width: 15%;" | Y
 +
| [[Master Portal sshkey endpoint | SSH public key management Endpoint]]
 +
 
 +
|-
 +
| style="width: 25%;" | /sshkeylisting
 +
| style="width: 15%;" | '''N'''
 +
| [[Master Portal sshkey endpoint | endpoint for listing registered username/pubkey pairs]]
 +
 
 +
|-
 +
| style="width: 25%;" | /revoke
 +
| style="width: 15%;" | Y
 +
| Revocation endpoint to revoke refresh tokens (only [https://github.com/rcauth-eu/aarc-master-portal/blob/v0.2.0/RELEASE-NOTES.md#revocation-of-refresh-tokens v0.2.0] and up).
 +
 
 +
|-
 +
| style="width: 25%;" | /admin-register
 +
| style="width: 15%;" | Y
 +
| Administrative clients registration endpoint (only [https://github.com/rcauth-eu/aarc-master-portal/blob/v0.2.0/RELEASE-NOTES.md#client-management-api v0.2.0] and up).
 +
 
 +
|-
 +
| style="width: 25%;" | /clients
 +
| style="width: 15%;" | Y
 +
| API endpoint for administrative clients (only [https://github.com/rcauth-eu/aarc-master-portal/blob/v0.2.0/RELEASE-NOTES.md#client-management-api v0.2.0] and up).
 
|}
 
|}
  
Line 126: Line 161:
  
 
<ol style="list-style-type:upper-roman">
 
<ol style="list-style-type:upper-roman">
   <li>External : The VO Portal calls the Master Portal to initiate an OIDC/OA4MP authorization request with its specific [https://docs.google.com/document/d/1cs3peO9FxA81KN-1RC6Z-auEFIwRbJpZ-SFuKbQzS50/pub#h.dzjw7gmgfel parameters]. This starts the AUTHORIZATION_ACTION_START flow</li>
+
   <li>External : The VO Portal calls the Master Portal to initiate an OIDC/OA4MP authorization request with its specific [http://goo.gl/VnMKXS#h.dzjw7gmgfel parameters]. This starts the AUTHORIZATION_ACTION_START flow</li>
 
   <li>Internal : The Master Portal (OA4MP Client) calls the /authorize endpoint to notify the Master Portal (OA4MP Server) that user authentication has concluded. Here, a different set of parameters are sent: '''code''' & '''state''' for session identification, '''username''' to identify the authenticated user. This starts the AUTHORIZATION_ACTION_OK flow.</li>
 
   <li>Internal : The Master Portal (OA4MP Client) calls the /authorize endpoint to notify the Master Portal (OA4MP Server) that user authentication has concluded. Here, a different set of parameters are sent: '''code''' & '''state''' for session identification, '''username''' to identify the authenticated user. This starts the AUTHORIZATION_ACTION_OK flow.</li>
 
   <ol style="list-style-type:square">
 
   <ol style="list-style-type:square">
Line 132: Line 167:
 
   </ol>
 
   </ol>
 
</ol>
 
</ol>
 +
 +
===== The IdP Hint =====
 +
 +
Users authenticating to the Master Portal will always get redirected to the Delegation Server's WAYF. Here, the user will have to choose the correct Identity Provider (IdP) in order to proceed with the authentication. This extra manual step could degrade user experience (e.g. by having to choose the same IdP many times, or by having the user choose the right IdP). In order to prevent this from happening an additional request parameter has been implemented called the '''idphint'''.
 +
 +
The '''idphint''' parameter can be sent to the /authorize endpoint together with the rest of the standard [http://goo.gl/VnMKXS OIDC] request parameters. The value of the '''idphint''' should be the url encoded [https://wiki.shibboleth.net/confluence/display/CONCEPT/EntityNaming entityID] of the user's home IdP. The Master Portal will simply forward every non-OIDC specific parameter (including the '''idphint''') to the Delegation Server. The Delegation Server in turn will use this request parameter to notify its WAYF about the users' preferred home IdP, which then will redirect the browser automatically to the requested IdP's authentication page, without requiring any prior user interaction.
  
 
==== Enabling crossContext in Tomcat ====
 
==== Enabling crossContext in Tomcat ====
  
The two Master Portal components are separate web applications living inside the same web container (tomcat). In order to be able to forward requests internally between the two (without going through the browser) the [https://tomcat.apache.org/tomcat-7.0-doc/config/context.html crossContext] flag has to be enabled in the web container. This will allow all web application to get access to each other, within the container. You can enable this in tomcat in ''CATALINA_HOME\conf\context.xml''
+
The two Master Portal components are separate web applications living inside the same web container (tomcat). In order to be able to forward requests internally between the two (without going through the browser) the [https://tomcat.apache.org/tomcat-7.0-doc/config/context.html crossContext] flag has to be enabled in the web container. This will allow all web application to get access to each other, within the container. You can enable this in tomcat in ''CATALINA_HOME/conf/context.xml''
  
 
  <Context crossContext="true">     
 
  <Context crossContext="true">     
Line 142: Line 183:
  
 
=== Session keeping ===
 
=== Session keeping ===
 +
 +
==== Between MP Server and MP Client ====
 +
 +
The MP Server does not do any user authentication locally, but rather forwards authentication requests to the Delegation Server, via the MP Client, as described in the [[#Authentication_Flow | authentication flow]] above, introducing a split authorization flow of the MP Server: '''AUTHORIZATION_ACTION_START''' and '''AUTHORIZATION_ACTION_OK'''. As a result, the MP server and client need to track their session across this split.
 +
 +
The MP Server stores session information in its back-end database in a structure called ''transactions'' (see [https://github.com/rcauth-eu/OA4MP/blob/v4.2-RCauth-1/oa4mp-server-admin-oauth2/src/main/resources/oauth2-mysql.sql oa4mp transactions]). The ''transactions'' are indexed by the authentication '''code''' (same as ''temp_token''). In order to retrieve the current transaction the authentication ''code'' is needed. Therefore, in order to keep session across the authorization flow split, the '''code''' has to be transmitted to and from the MP Client. The MP Client adds a new database entry called [[Master_Portal_Administrator_Guide#Database_2 | mp_server_request_code]] which is used to store the '''code''' parameter received from the MP Server.
 +
 +
Similarly, the MP Client stores session information in its back-end database in a structure called ''assets'' (see [https://github.com/rcauth-eu/OA4MP/blob/v4.2-RCauth-1/oa4mp-client-oauth2/src/main/resources/oauth2-mysql.sql oa4mp assets]). The ''assets'' are indexed by a session '''identifier''' which is an arbitrary identifier that gets created by the MP Client at the start of a request. The MP Server stores this '''identifier''' in a new database entry called [[Master_Portal_Administrator_Guide#Database | mp_client_session_identifier]]. The MP Server does not use this stored value during the authentication flow, but only during the proxy retrieval flow. Using this '''identifier''' the MP Client will look up its pending session with the Delegation Server and retrieve credentials on demand.
 +
 +
==== Between VO Portal and MP Server ====
 +
 +
In order to prevent [https://tools.ietf.org/html/rfc6749#section-10.12 CSRF] the [http://goo.gl/VnMKXS OIDC/OA4MP] specs recommend using the '''state''' as a request value in the [[#Authentication_Flow | authentication flow]]. However, since the MP Server does not store the '''state''' value in its ''transactions'' back-end, it cannot retrieve its value after the split authorization flow between the MP Server and MP Client is finished. In order to still allow the MP Server to send back the '''state''' to the VO Portal, the MP Client instead will store the received '''state''' value in a new database entry called [[Master_Portal_Administrator_Guide#Database_2 | mp_server_request_state]], and send it back to the MP Server.
 +
 +
==== Between Browser and MP Client ====
 +
 +
The MP Client uses a session '''identifier''' to index its sessions. These '''identifiers''', also described [[#Between_MP_Server_and_MP_Client | above]] are sent to the user's browser in a session cookie called '''master_portal_client_req_id'''. Once the OIDC authentication flow has completed between the MP Client and the Delegation Server, the browser is redirected to the '''redirect_uri''' endpoint of the MP Client (/ready endpoint). The MP Client then extracts the '''master_portal_client_req_id''' cookie and looks up the pending session.

Latest revision as of 13:18, 5 September 2019

The Master Portal stands at the heart of the RCauth and MasterPortal setup. The Master Portal caches long lived user proxies into its MyProxy Crendential Store, and returns short lived proxies on demand for authenticated users via the VO Portal.

Structure

The Master Portal is made up internally of both an OA4MP Server and Client. For the purpose of the VO Portal, the Master Portal is an OA4MP Server. For the purpose of the Delegation Service the Master Portal is an OA4MP Client. The motivation for having OA4MP Client and Server rolled into one unit was to have a mediator between the VO Portal and the Delegation Server (Online CA), caching user credentials (long lived proxies) passing through it, while also hiding all the complexity for the VO portals.

Masterportal-structure.svg

Most of the endpoints in the above diagram are part of the standard OIDC/OA4MP protocol. The new endpoints are marked with blue:

The Master Portal (OA4MP Server) takes registrations from VO Portals. Once a VO Portal is registered and approved, it can use the Master Portal (OA4MP Server) exposed endpoint in order to start an OIDC/OA4MP flow(1) between VO Portal and Master Portal. The only deviation from the original flow is that here, instead of calling the GetCert Endpoint, the VO Portal calls the GetProxy Endpoint in the last step.

The Master Portal (OA4MP Client) component has to be registered as client with the Delegation Server (OA4MP Server). It starts a second OIDC/OA4MP flow(2) between Master Portal and Delegation Server. In this second flow, the last step, involving the GetCert Endpoint, is left unchanged.

The two components will interact for the following reasons:

  • User Authentication : the Master Portal is not configured to authenticate users directly, instead user authentication requests are forwarded to the Delegation Server. In the diagram the /startRequest and /authorize calls serve this purpose.
  • Certificate Requests : the Master Portal cannot issue new credentials for authenticated users, it can only retrieve credentials for users who already have a valid credential in the MyProxy Credential Store. Asking for a new credential (either for new users, or users who's credential expired in the credential store) can be done by calling a GetCert Endpoint. The /forwardgetcert is used for this.

Authentication Flow

The Master Portal does not authenticate users locally, instead authentication requests are forwarded to the Delegation Server. An unmodified OA4MP Server can be configured to authenticate users either by their password credentials or via shibboleth, but has no support for authN request forwarding. The Master Portal implements this missing authN forwarding.

Masterportal-authN-seq.svg

The Master Portal authN flow is divided into two sub-flows:

  1. AUTHORIZATION_ACTION_START : the user is not yet authenticated
    1. The VO Portal starts an OIDC/OA4MP flow by sending an authorization request to the Master Portal (OA4MP Server).
    2. According to the OA4MP mini-protocol, a call to the /authorized endpoint is made to retrieve the code & state of the initiated transaction.
    3. The authN request forwarding is done by triggering a second OIDC/OA4MP flow between the Master Portal (OA4MP Client) and the Delegation Service. The /startRequest endpoint will kick off this second flow.
      1. The code & state are sent from the Master Portal (OA4MP Server) to the Master Portal (OA4MP Client) for session keeping.
    4. The Master Portal (OA4MP Client) starts the second OIDC/OA4MP flow by sending an authorization request to the Delegation Server.
      1. The identifier is send along in a cookie. This is used to keep session between the user (browser) and the Master Portal (OA4MP Client).
    5. When the user is correctly authenticated, the Delegation Server will trigger a browser redirect to the redirect_uri (/ready endpoint) on the Master Portal (OA4MP Client). This endpoint has to be pre-registered with the Delegation Server!
      1. The identifier (from step a.4) is extracted from the cookies in order to identify the pending authN session of Master Portal (OA4MP Client).
    6. The Master Portal (OA4MP Client) retrieves an Access Token from the Delegation Server.
    7. The Master Portal (OA4MP Client) retrieves information of the authenticated user from the Delegation Server. This includes the username.
  2. AUTHORIZATION_ACTION_OK : the user is authenticated
    1. The authenticated username is send back from the Master Portal (OA4MP Client) to the Master Portal (OA4MP Server) to its /authorize endpoint.
      1. The code & state (received in step a.3) are also send back in order to identify the pending authN session of Master Portal (OA4MP Server).
    2. The Master Portal (OA4MP Server) answers to the authorization requests from step a.1.

Endpoints

Both Master Portal components expose a set of endpoints, however some of these endpoints are only meant to be called internally. Make sure to restrict access to internal endpoints!

The Master Portal (OA4MP Server) hosts most of the forward facing endpoints:

Endpoint Exposed Description
/register Y Client Registration Endpoint
/authorize Y Authorization Endpoint
/authorized N Private Authorization Endpoint
/token Y Token Endpoint
/userinfo Y Userinfo Endpoint
/.well-known/openid-configuration Y well-known openid configuration Endpoint
/getproxy Y GetProxy Endpoint, see also its implementation
/sshkey Y SSH public key management Endpoint
/sshkeylisting N endpoint for listing registered username/pubkey pairs
/revoke Y Revocation endpoint to revoke refresh tokens (only v0.2.0 and up).
/admin-register Y Administrative clients registration endpoint (only v0.2.0 and up).
/clients Y API endpoint for administrative clients (only v0.2.0 and up).

The Master Portal (OA4MP Client) on the other hand, has most of its endpoint private:

Endpoint Exposed Description
/startRequest N Initiates an OIDC/OA4MP flow to the Delegation Server
/forwardgetcert N Initiates /getcert call to the Delegation Server
/ready Y Registered redirect_uri called by the Delegation Server

Discussion on the /authorize endpoint

As described in the Authentication Flow, the /authorize endpoint living on the Master Portal (OA4MP Server) is called twice. There are two types of calls:

  1. External : The VO Portal calls the Master Portal to initiate an OIDC/OA4MP authorization request with its specific parameters. This starts the AUTHORIZATION_ACTION_START flow
  2. Internal : The Master Portal (OA4MP Client) calls the /authorize endpoint to notify the Master Portal (OA4MP Server) that user authentication has concluded. Here, a different set of parameters are sent: code & state for session identification, username to identify the authenticated user. This starts the AUTHORIZATION_ACTION_OK flow.
    1. All three variables (code, state and username) are internally used attributes scoped by the lifetime of the HttpServletRequest java object
The IdP Hint

Users authenticating to the Master Portal will always get redirected to the Delegation Server's WAYF. Here, the user will have to choose the correct Identity Provider (IdP) in order to proceed with the authentication. This extra manual step could degrade user experience (e.g. by having to choose the same IdP many times, or by having the user choose the right IdP). In order to prevent this from happening an additional request parameter has been implemented called the idphint.

The idphint parameter can be sent to the /authorize endpoint together with the rest of the standard OIDC request parameters. The value of the idphint should be the url encoded entityID of the user's home IdP. The Master Portal will simply forward every non-OIDC specific parameter (including the idphint) to the Delegation Server. The Delegation Server in turn will use this request parameter to notify its WAYF about the users' preferred home IdP, which then will redirect the browser automatically to the requested IdP's authentication page, without requiring any prior user interaction.

Enabling crossContext in Tomcat

The two Master Portal components are separate web applications living inside the same web container (tomcat). In order to be able to forward requests internally between the two (without going through the browser) the crossContext flag has to be enabled in the web container. This will allow all web application to get access to each other, within the container. You can enable this in tomcat in CATALINA_HOME/conf/context.xml

<Context crossContext="true">     
...
</Context>

Session keeping

Between MP Server and MP Client

The MP Server does not do any user authentication locally, but rather forwards authentication requests to the Delegation Server, via the MP Client, as described in the authentication flow above, introducing a split authorization flow of the MP Server: AUTHORIZATION_ACTION_START and AUTHORIZATION_ACTION_OK. As a result, the MP server and client need to track their session across this split.

The MP Server stores session information in its back-end database in a structure called transactions (see oa4mp transactions). The transactions are indexed by the authentication code (same as temp_token). In order to retrieve the current transaction the authentication code is needed. Therefore, in order to keep session across the authorization flow split, the code has to be transmitted to and from the MP Client. The MP Client adds a new database entry called mp_server_request_code which is used to store the code parameter received from the MP Server.

Similarly, the MP Client stores session information in its back-end database in a structure called assets (see oa4mp assets). The assets are indexed by a session identifier which is an arbitrary identifier that gets created by the MP Client at the start of a request. The MP Server stores this identifier in a new database entry called mp_client_session_identifier. The MP Server does not use this stored value during the authentication flow, but only during the proxy retrieval flow. Using this identifier the MP Client will look up its pending session with the Delegation Server and retrieve credentials on demand.

Between VO Portal and MP Server

In order to prevent CSRF the OIDC/OA4MP specs recommend using the state as a request value in the authentication flow. However, since the MP Server does not store the state value in its transactions back-end, it cannot retrieve its value after the split authorization flow between the MP Server and MP Client is finished. In order to still allow the MP Server to send back the state to the VO Portal, the MP Client instead will store the received state value in a new database entry called mp_server_request_state, and send it back to the MP Server.

Between Browser and MP Client

The MP Client uses a session identifier to index its sessions. These identifiers, also described above are sent to the user's browser in a session cookie called master_portal_client_req_id. Once the OIDC authentication flow has completed between the MP Client and the Delegation Server, the browser is redirected to the redirect_uri endpoint of the MP Client (/ready endpoint). The MP Client then extracts the master_portal_client_req_id cookie and looks up the pending session.