PortalProtect supports issuing and using Oauth2 bearer tokens for service calls.

PortalProtects Oauth2 support is based upon the Oauth2 protocol is documented in the internet standard draft RFC6749.

PortalProtect can act as a Resource Owner, an Authorization Server and as a Resource Server as defined in the standard.

Usage Scenario

Imagine this usage scenario;

DataVaultCompany allows its registered users to store information ranging from their name, email and physical address to their visa card numbers and pension and health insurance policies.

DataVaultCompany has very strict authentication and customer verification procedures as well as high data integrity so the information it holds on behalf of its customers is extremely accurate, and ranging from semi-public information to extremely private and highly secured information.

Now, a broker company (TheBrokerCompany) wishes to provide a service to some user where it needs the end user's verified name and address. It also provides premium services to customers like helping them select the correct pension insurance provider.

Now, using Oauth2 with PortalProtect, DataVaultCompany allows the user to select which information it wants to share with TheBrokerCompany, ranging from just name and email address to sensitive secure information.

So, when the user accesses TheBrokerCompany’s website then they redirect the users browser to DataVaultCompany using an Oauth2 “Authorization Request” – the end user identifies himself to DataVaultCompany and allows TheBrokerCompany to access his name and email address, which TheBrokerCompany knows to be verified by DataVaultCompany.
So, TheBrokerCompany receives an Oauth2 “Authorization Grant” with an authorization code. This code is then used along with TheBrokerCompany’s client secret (password) in a webservice call directly from TheBrokerCompany to DataVaultCompany.
DataVaultCompany then exchanges the authorization code with a bearer token with a specified duration – while this token is valid, TheBrokerCompany can use it in an HTTP Authorization header when making webservice calls to TheDataVaultCompany on behalf of the user, and they will get access to the data that the user allowed.

At a later point, they can ask the user to authorize them to access more secure data, such as the health insurance information or whatever else kind of data that the user authorizes TheDataVaultCompany to share with TheBrokerCompany.

Technical Information

Normally, the dispatcher uses a session cookie to store PP session information in, but an authentication plugin can issue a bearer token which can be used instead of a session cookie as a way of identifying the client.

The dispatcher will look at the configured Oauth2 rules (see reference section of this document for information about the oauthrule.xxxx and oauth.realmname properties).

If the request matches these configured rules, it will not look for a session cookie, but instead for a bearer token in either the Authorization HTTP header, or as an URL parameter.
If the oauthrule does not define the check as optional, and if no bearer token is present, the dispatcher will send a “401 Authentication Required” error to the user with a WWW-Authenticate header asking it to use Bearer authentication method.

If the bearer token is found, it will call the agent’s (Agent.getInstance().getSessionFromTicket() method) with the bearer token, and the registered Oauth2 authentication plugin in the dispatcher will be called with the bearer token and it needs to fill in the session with all previously stored information about the user. It is up to the authentication plugin how it stores/retrieves this information.

One way of providing this information is demonstrated with the sample Authentication Plugin “DemoOAuth2AuthenticationPlugin” provided in source code form along with the PortalProtect’s distribution. It works together with an Oauth2Servlet in the provided sample web application, which allows the user to identify himself and prompts him to grant access to a client asking for an authorization code / bearer token.

Example Requests

An example request to obtain a new bearer toking using the implicit grant method is here:
https://www.portalprotect.dk/oauth2/auth?response_type=token&client_id=broker&redirect_uri=https%3A%2F%2Fwww.some.broker.com/oauth2&scope=name+email&state=somestate

This will allow the user to authenticate if he has not done so already, and grant access to the client. Once granted, the web application will redirect the user back to the specified redirect_uri, but with the bearer token added as per the oauth specification, the URL could look like this:
https://www.some.broker.com/oauth2#access_token=OWVlY2YxNWMtNjAwYi00N2FlLTliMGYtMTdhN2E1NDlmNmVm&token_type=Bearer&expires_in=3600&state=somestate

Since implicit grant is used, the access token is in the URL fragment so it will not be sent to the server, but it is accessible to a javascript application running within the user's browser. This application can then use the token to make requests to services with the HTTP header “Authorization: Bearer OWVlY2YxNWMtNjAwYi00N2FlLTliMGYtMTdhN2E1NDlmNmVm” – assuming the URL for the service call matches a configured oauthrule, the server can then return this information.

Example
https://www.portalprotect.dk/oauth2/test?access_token=OWVlY2YxNWMtNjAwYi00N2FlLTliMGYtMTdhN2E1NDlmNmVm

Will return this JSON response if the token is valid:
{“id”:”userxyz”,”name”:”User XYZ Name”}