Usage of "OAuth2" policy action in CentraSite and Mediator
1. Introduction
2. Prerequisite
3. Configurations
3.1 Mediator Configurations
3.1.1 watt.server.auth.skipForMediator
3.1.1 The pg.oauth2 Parameters
3.2 Asset Creation and Deployment
3.3 Asset Consumption
4. Fetching and Using Your OAuth2 Access Tokens for Consumption
5. Overview of Access Keys
6. Invocation through SOAP UI
7. Troubleshooting
Introduction
Mediator extracts the OAuth2 access token from the request’s HTTP header at run time and searches its list of consumers for the client that is defined by that access token in Integration Server.
The type of OAuth2 authorization grant that Mediator supports is "Client Credentials". Client credentials are used as an authorization grant when the client is requesting access to protected resources based on an authorization previously arranged with the authorization server. That is, the client application gains authorization when it is registered with CentraSite.
OAuth2 Sequence Flow
Prerequisite
This tutorial assumes some basic knowledge with Mediator and Integration Server.
You must set the following parameters in Mediator to support OAuth2:
- Create a HTTPS port in Integration Server and enable it in the Mediator Administration screen in the General screen.
- Set watt.server.auth.skipForMediator to true and Set the pg.oauth2.* parameters as appropriate
- Create a target instance in CentraSite pointing to the mediator url where it is available.
Note: Mediator hosts a predefined service that consumers must invoke in order to receive OAuth2 access tokens
Configurations
Mediator Configurations
watt.server.auth.skipForMediator
To set watt.server.auth.skipForMediator =true in the Integration Server Extended settings. This parameter specifies whether Integration Server authenticates requests for Mediator. You must set this parameter to true.
To do this
-
- In the Integration Server Administrator, click Settings > Extended
- Click Show and Hide Keys.Look for the watt.server.auth.skipForMediator property and ensure it is set to true.
- If the watt.server.auth.skipForMediator property is not present, add it as follows:
a. Click Edit Extended Settings.
b. Type watt.server.auth.skipForMediator=true on a separate line.
c. Click Save.
d. Restart Integration Server
The pg.oauth2 Parameters
For security reasons it is recommended to use HTTPS in your production environment.If you will be using HTTPS as the transport protocol over which the OAuth2 access tokens will be granted authorization, you must set the following parameters in the Mediator properties file, which is located in: Integration Server_directory \instances\instance_name \packages\WmMediator\config\resources\pg-config.properties
pg.oauth2.isHTTPS: Specifies the transport protocol over which the OAuth2 access tokens will be granted authorization. Set this parameter to true for HTTPS (the default) or false for HTTP
pg.oauth2.ports: If pg.oauth2.isHTTPS is set to true, specify a comma-separated list of the HTTPS ports on which the service mediator.oauth2.getOAuth2AccessToken
will be available.
Asset Creation and Deployment
- Create a webservice asset in CentraSite using Business UI pointing to the native webservice uri where it is hosted.
- Once the asset is created, click on "Virtualize" action in the "Action Bar" of the webservice asset.
- Once you click on the action you would be prompted to provide the new Virtual alias name and select the desired endpoint to be virtualized, Once done click on "Next".
- Once the virtual service is created, in the asset details under the "Actions Bar" click on the action "API Consumption Settings" and select "OAuth2" as the asset consumption mechanism.
- There are other parameters as well like the "Refresh Token After" which specifies the renewal time of token being used.
- If you would like to have the Approval to be triggered for managing the token generation / renewal process, You can do that by enabling the check box "Require Approval" which is an optional settings.
- Once the settings are done click on "Configure"
- Now click on "Publish" Action and select the mediator / target instance where you desire to deploy the asset and select the option "Expose to Consumers" and click on "Publish" button
- VSD Snippet
<enforcement-actions allow-anon="false">
<expressions>
<expression>
<params identify="strict" type="oAuth2Token" validate="true" />
</expression>
</expressions>
</enforcement-actions>
|
Asset Consumption
- Once the asset is published on to the mediator instance, the consumers would be able to view the asset in the CentraSite and the intrested consumer would proceed to view the details of the asset and click on the action "Consume"
- Provide the details of how you would like to consume the asset, In this case since we have enabled only "OAuth" way of doing it, it would be already selected by default. Once provide the reason for request and the Consume Application name click on "Consume" button as a result a consumer application asset with the name provided here would be created in CentraSite.
- Once its is done you would the list of consumers in the Basic Information to have increased(hint: if there is no approval flow involved), By clicking on the number as below it would show the "OAuth2 Client" asset created for the user(Internal\inosec2) who would like to consume the asset as shown below.
- Following the above link would show the "OAuth2 Identification Details" for the asset using which we can consume the Virtual Service.
A brief introduction about the parameters seen as part of the "Identification Details" profile which are used for generating the OAuth2 Access token going forward.
-
- Client ID: It is the unique ID of the consumer created in the "Integration Server"
- Client Secret: It is a unique code/password used to validate the consumer
- Scope: Scope is the name of the Virtual Service asset being deployed / ready for consumption
- Access Token Request URI: this is the uri which the consumer should use to generate an access for access the Virtual Service
Fetching and Using Your OAuth2 Access Tokens for Consumption
Mediator out of the box provides a REST based service which would generate an OAuth2 Access token for the virtual service asset deployed in mediator.
You need to obtain an OAuth2 access token by passing your client credentials to the Mediator-hosted REST service pub.mediator.oauth2.getOAuth2AccessToken. This service will provide an OAuth2 access token that you can subsequently include in your requests to call the API.
The service's input parameters are:
-
-
client_id -
client_secret -
scope (optional) - Set the Content-Type and the Accept HTTP headers to application/json
-
Copy the access token uri and provide the input from a REST based client to generate the access token, In this case we are using SOAP UI to create a rest service pointing to the access uri
(For example: https://<IS Host IP>:<HTTPS Port>/rest/pub.mediator.oauth2.getOAuth2AccessToken)
Over here what we see is the OAuth2 token is now successfully generated.
Overview of Access Keys
Often users who have access to the the services they are consuming they can get an overview of their access keys in Business UI by landing in the user preferences screen.
Invocation through SOAP UI
- Create a project in SOAP UI referring to the uri of the deployed asset
- Add the custom HTTP Header (Authorization) with the value as "Bearer --accesstoken-- "
- Invoke the service
Troubleshooting
|
S. No
|
Exception
|
What happened
|
What should be done
|
|---|---|---|---|
| 1 |
Port not accessible {"$errorDump":"com.wm.app.b2b.server.PortAccessException: [ISS.0084.9101] Access Denied\r\n\tat
|
While accessing the Mediator Hosted REST service which generates the OAuth2 access token you are getting an access denied exception while accessing the port | Check if the port is having Enabled to access and also the Access mode is allow which is deny by default |
| 2 |
Invalid client id/secret during token generation { error: "invalid_request" error_description: "[ISS.0010.8008] client_id does not identify a registered client." } |
Mismatch of the client id and the client secret provided |
Check if the client_id and the client_secret values provided is correct. |
| 3 | HTTP Status 405 Method Not Allowed | The REST Service uri package is invalid |
The uri to get the access token should be https://<ISHost>:<HTTPSPortNumber>/rest/pub.mediator.oauth2.getOAuth2AccessToken |
| 4 | Mediator encountered an error:Consumer could not be identified. Anonymous access is not allowed for this service! | Auth token not provided during service invocation | Provide the Authorization header with "bearer accesstokenvalue" as custom header |
| 5 | HTTP Status 401 Unauthorized , invalid_token | The access token is either invalid or expired | Regenerate a new token |
| 6 | HTTP Status 403 Forbidden, insufficient_scope | Integration Server rejected the request to access this resource. The access token's scope is insufficient to access the resource. | Check if the property watt.server.auth.skipForMediator=true if not enable it in the Extended settings |
Click here to download PDF version of this tutorial.