By Thangavelu, Dharmaraj
Supported Versions: 10.2 and below
webMethods API Gateway tutorial
Introduction:
“OAuth is an open standard for authorization, commonly used as a way for Internet users to authorize websites or applications to access their information on other websites but without giving them the passwords” – Wikipedia
OAuth2 defines the following roles:
-
Resource Owner
- The end user who can grant access to a protected resource. In API Gateway this could be any IS user.
-
Resource Server
- The server that holds the resource. API Gateway is the resource server which holds the resources(services)
-
Client
- The consumer application that is registered with API Gateway
-
Authorization Server
- The server that is authorizing the client applications to access a protected resource. IS will be the authorization server in API Gateway.
OAuth2 defines the following grant types
- Authorization Grant
- Implicit
- Client Credentials
The following diagrams, capture the execution flow for all of the above grant types:
Tutorial
The application we will use for this tutorial is a Health Insurance Quote Aggregator. This Application takes the users health data and submits to multiple health insurance providers using the paid services provided by them and lists all the quotes obtained from the services. As a user of this application, one might not want to give the health data to all the health insurance providers, and also want to approve the specific providers whom which his details could be sent to. This could be done in multiple ways; we consider some approaches and see where OAuth will simplify.
Without OAuth:
This application can send a list of supported health insurance providers to the user and the user can choose which providers to send the data.This will require the application to authenticate/authorize the user for every health insurance provider service. Also the user will have to provide the passwords of all the insurance providers to access the service on behalf of the User. This was the approach used before OAuth.
With OAuth2:
This application registers itself with one trusted OAuth2 authorization server. For simplicity let’s assume all the health insurance providers have registered with the same authorization server as a resource. Then the consent and authorization can be done for all the providers at once. The User need not give out the passwords to the application.
We will go through the following steps in this tutorial
- Importing health insurance provider services into API Gateway
- Enforcing OAUTH2
- Creating Health Insurance Quote Aggregator Application in gateway
- Registering APIs with this application
- Getting bearer token
- Refreshing Access Token
- Enabling OAuth2 authorization through HTTP
(1) Importing health insurance provider services into API Gateway
Import the health insurance provider services using the following screen.
(2) Enforcing OAuth2:
- Edit HealthInsuranceProvider1 API in API Gateway application
- Click Edit
- Click Identity and Access management
- Click Identify and authenticate icon
- Tick OAuth2 Token
This procedure will enforce OAuth authorization for this service; repeat the same for all the other health insurance providers.
(3) Creating Health Insurance Quote Aggregator Application in API Gateway
Now we need to create the application in API Gateway, This will create the OAuth2 Credentials by default.
(4) Registering APIs with this application
The APIs that we created should be associated with this application as shown below
(5)Getting bearer token:
We will use the postman app for google chrome in this tutorial to get the bearer token. The following details are needed to get the bearer token.
Registering redirect url.
- In OAuth2, the authorization server sends the authorization code to the redirect url that is specified in the client application. In order to get the authorization code through postman we need update the API Gateway application with the following url(https://www.getpostman.com/oauth2/callback). In practice, this redirect url should be one of your application url to receive the authorization code.
- Auth URL
- https://<IS_HOST>:<IS_PORT>/invoke/pub.apigateway.oauth2/authorize
- Access Token URL
- https://<IS_HOST>:<IS_PORT>/invoke/pub.apigateway.oauth2/getAccessToken
- Client ID
- Could be found in API Gateway application details page (See above picture)
- Client Secret
- Could be found in API Gateway application details page
Postman UI for entering OAuth 2.0 Authorization details
Once the Request Token is clicked, you will be getting this popup with the services to which you want to give access to. Here we are approving Provider1 and Provider3
Once it is approved, Postman will receive the bearer token, and this token could be used to invoke the HealthInsuranceProvider services.
(6) Refreshing Access Token
While getting the bearer token as in the previous step, we can optionally get a refresh token, that could be used to get a new access(bearer) token without having user to grant the request again.
The OAuth2 credentials should be edited to allow generating refresh tokens.
Once the token refresh limit is set to non-zero. A refresh token will be generated as part of the access token that is generated. As shown below
In order to refresh the access token, the request should be formed as shown below.
The following endpoint should be used.
https://<IS_HOST>:<IS_PORT>/invoke/pub.oauth/refreshAccessToken
The output would be like
(7) Enabling OAuth2 authorization through HTTP
The entire process could be executed using http instead of https. This needs the following configurations.
Enable IS to accept HTTP for OAuth2
Enable API Gateway to accept HTTP for OAuth2
(8) Remote IS Authorization server
In order to use a remote IS as authorization server, one has to configure the remote server is IS. There is no configuration required in API Gateway. The clients and scopes will get automatically created in the remote IS when an API or application is created in API Gateway.
Use the following URLs to get access tokens and refresh tokens.
https://<Remote_IS_HOST>:<Remote_IS_PORT>/invoke/pub.oauth/getAccessToken
https://<Remote_IS_HOST>:<Remote_IS_PORT>/invoke/pub.oauth/refreshAccessToken
Troubleshooting tips:
HTTP:
If you specify the http authorization endpoint, you will have a access denied error in the logs. To allow access through http you must follow the steps in section 7
Incorrect authorize URL:
If the popup for authorize URL is not shown, most likely the authorize URL is wrong. Fix the URL as specified in section 5
Other Issues:
Turn on trace mode for APPLICATION Management and IAM modules to see trace logs related to OAuth.
