Master Portal Internals

The Master Portal stands at the heart of the AARC Pilot. 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.

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

• /getproxy : retrieves (VOMS) proxies via the GetProxy 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 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.

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
/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). See v0.2.0 RELEASE NOTES.
/admin-register	Y	Administrative clients registration endpoint (only v0.2.0 and up). See v0.2.0 RELEASE NOTES.
/clients	Y	API endpoint for administrative clients (only v0.2.0 and up). See v0.2.0 RELEASE NOTES.

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 Serve's WAYF. Here, the user will be able to choose his home institution in order to proceed with the authentication. As the home IdP of a user hardly ever changes, this extra manual step could degrade user experience since it will require the same user interaction over and over again. 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 replay every non-OIDC specific parameter (including the idphint) to the Delegation Server. The Delegation Server will use this request parameter to notify the WAYF of the users' preferred home IdP, redirecting the browser automatically to the requested home 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 it forwards authentication requests to the Delegation Server, via the MP Client, as described in the authentication flow. This introduces a split authorization flow of the MP Server, marked by the two states described above: AUTHORIZATION_ACTION_START and AUTHORIZATION_ACTION_OK. In order to keep a consistent session across this split you will have to know about how MP Server and MP Client keeps session.

The MP Server stores session information in its backend 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 backend 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 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

The OIDC/OA4MP specs recommend using the state as a request value in the authentication flow, in order to prevent CSRF. The MP Server does not store the state value in its transactions backend, therefore there is no way to retrieve this value after the authorization flow split between the MP Server and MP Client. Since the MP Server has to be able to send the state back to the VO Portal, the MP Client will store the received state value in a new database entry called mp_server_request_state, and send it back to the MP Server.

Betweeen 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.