Master Portal Internals

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.

Structure

The Master Portal is made up internally of a 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.

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 at the end, instead of calling the GetCert Endpoint, the VO Portal calls the GetProxy Endpoint.

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

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 /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 this second flow off.
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. 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!
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 endpoint, 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
/authorize	Y	Authorization Endpoint
/authorized	N	Private Authorization Endpoint
/token	Y	Token Endpoint
/userinfo	Y	Userinfo Endpoint
/getproxy	Y	GetProxy Endpoint

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

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>