This post is part III of a serie of posts about OAM's OAuth implementation.
Other posts can be found here:
Part I - explains the proposed architecture and how to enable and configure OAM OAuth Services.
Part II - describes a Business to Business use-case (2-legged flow);
Part III - deals with the Customer to Business use-case (3-legged flow), when the client code is running in the application server;
Part V - provides the source code and additional information for the use case implementation.
This post will cover the C2B (Customer to Business) Use Case, when the Client Application is running on the Server.
In this case, an end user accesses an Application, which needs to fetch data from a Resource Server in behalf of the end user, but without the end user providing his credentials to the Application.
The user has to provide his consent for the client application to access his resources in the Resource Server.
In this use case, all the code resides in the server and it is not visible to the end user.
Oracle recommends that customers install the latest bundle patch available for their specific IdM release. Bundle Patches might include important patches for OAuth implementation. You can find information about Bundle Patch History and Releases in the Support document "OAM Bundle Patch Release History (Doc ID 736372.1)". Please visit My Oracle Support (https://support.oracle.com) and search for Doc ID 736372.1.
Read this if you're using OAM R2PS3 (22.214.171.124)
This post was written based on OAM R2PS2 release. Even though most things are still the same on R2PS3 release, there are some subtle differences from one release to the other.
In OAM R2PS3, you need to deploy a webgate in front of your OAM servers in order to use the OAuth 3-legged flow.
The webgate is required to protect the OAuth consent page, otherwise you will get an error when trying to follow the 3-legged OAuth flow.
Review the documentation on how to install a supported webserver and deploy webgate here.
Deploy and register a webserver/webgate and configure the following resources in your application domain:
/ms_oauth/oauth2/oammsui/** - Excluded
/oam/** - Excluded
/ms_oauth/img/* - Excluded
/ms_oauth/style/* - Excluded
/ms_oauth/oauth2/endpoints/** - Excluded
/ms_oauth/oauth2/ui/** - Protected
In your webserver create a new conf file with the following directives
WebLogicCluster server1:port1, server2:port2
WebLogicCluster server1:port1, server2:port2
The following picture shows the flow between the different components
1. A User Agent, usually a browser, accesses the Application, starting the OAuth flow.
2. The Application detects that the user have not presented an Authorization Code, then it redirects the user to the OAM/OAuth authorization URL.
The redirect is a standard HTTP browser redirect that looks like this:
Some things to note here:
The Application identifies itself with its ID, client_id=customerClient;
The expected response type is the authorization code, response_type=code;
The redirect URI, to where the OAuth server will redirect the request with the authorization code as URL parameter after the user successfully logs in;
And lastly the requested Scope, Customer.Info and UserProfile.me
In this step the OAuth server checks if the requesting client is correctly registered, if it has the correct grant type enabled, in this case Authorization Code, if the redirect_uri is matches the one defined in the client configuration and if it is requesting a scope allowed for this client.
If the conditions above are not met, the OAuth server send and error back and does not proceed to the user authentication.
3. OAuth Server redirects the user to OAM Login Page.
4. User logs in with his credentials.
5. Since the user has started an OAuth flow in step 1, the OAuth server needs the user consent to provide a token to this application which will be used to access the user resource on the Resource Server.
6. OAuth server redirects the user to the consent page so the user can consent or reject the Application access to his resources.
The consent page looks like this:
7. The user grants access to the CustomerClient Application
8. The OAuth server returns the Authorization Code the the URI defined in the redirect_uri as an URL parameter.
The response looks like this:
9. The Application then is able to extract the Authorization Code from the URL parameter and request the OAuth Server for an Access Token. The request would look like this in curl:
Note that the Application passes its credentials enconded as 64Base in the Authorization header, the redirect URI, the grant type and the Authorization Code.
10. The OAuth Server checks the Authorization Code, if the grant type is enabled for this client and if its credentials are correct before issuing the Access Token.
11. OAuth Server send the Access Token back to the Application in the following format:
12. The application is able now to make a call to a remote service – The Resource Server – using the Access Token.
13. As in the same case of the B2B, the Resource Server is another OAuth client, with the particularity that is does not have any grant or scope defined to it.
It just needs to validate the token passed by remote clients. The only detail here is that this client needs to have the option to “Allow Token Attributes Retrieval” enabled, if it wants to perform Token Introspection, that is, return additional values, rather than just receiving a “valid” status from the OAuth Server.
14. The OAuth Server validates the Token and returns additional attributes.
The validation would look like this:
Note that the token, in a C2B use case, represents both the OAuth client ("oracle.oauth.client_origin_id":"customerClient") and the end user ("prn":"paulo").
15. The Resource Server returns the requested resource to the Client Application
16. The Client Application presents the results to the user agent.
To implement the C2B use case, a standard Java Servlet will be used, CustomerClient.java, that is very similar with the B2B use case, but it requires the user consent to allow the client application to access the user resources in its behalf.
This servlet, will obtain an Authorization Token, result of the end user authentication.
If this Servlet is protected by a OAM policy, and the user has already authenticated, the redirect to the authorization end point will provide the authentication token without the user having to login again.
With the Authorizaition Token, the Servlet can obtain and Access Token using the Authorization Code grant type, and will pass this Access Token to the Resource Server, when making the call to the Customer REST endpoint.
The Resource Service is implemented in a plain Java class using the Jersey framework to expose the Customer Service as a RESTful webservice.
The Resource Server also implements a Servlet Filter, that intercepts all incoming requests to validate the incoming Access Token before giving access to the REST Endpoint.
The relevant classes for this use case are: