Securing APIs using OAuth 2.0 with API Gateway as Resource Server and Remote Integration Server as Authorization Server
This use case explains, with a simple example, how to secure an API with OAuth2 authentication with API Gateway configured as Resource Server and remote Integration Server configured as the Authorization Server. The diagram illustrates the work flow for this use case.
Actors
Developers with basic knowledge on
webMethods API Gateway ,
Integration Server, OAuth2 architecture
Customers with basic knowledge about
webMethods API Gateway,
Integration Server, OAuth2 architecture
Before you begin
Ensure that you have:
Installed
Integration Server with
API GatewayKnowledge on any Rest Client
API Gateway up and running
Basic Flow
The following diagram depicts the high level steps of the basic flow for this use case.
Step 1: Configure remote Integration Server as authorization server
1. Disable HTTPS in OAuth in Integration Server.
In this example you disable HTTPS in the remote Integration Server OAuth as authorization is through HTTP.
a. Login to Integration Server with the URL. https://mahinename:5555
b. Navigate to Security > OAuth.
c. Click Edit OAuth Global Settings.
d. Uncheck Require HTTPS.
e. Click Save Changes.
2. Configure the following extended settings.
a. Navigate to Settings > Extended.
b. Click Show and Hide Keys.
c. Select watt.server.oauth.requireHTTPs and watt.server.oauth.requirePost .
d. Set both the value as false.
3. Create Client.
a. Navigate to Security > OAuth.
b. Click Client Registration.
c. Click Register Client.
d. Provide the following information:
Name:
OAuth Client Version:
1.0 Type:
Confidential Redirect URIs:
https://example.com/redirect Allowed Grants:
Authorization Code Grant,
Client Credentials Grant Expiration Interval:
Never Expires Refresh Count:
Unlimited e. Click Save .
Onsuccessfully saving the following message displays: Successfully registered client OAuth Client, version 1.0. To use the client credentials grant, this client must be given ACL permissions to access the resources in the client's scopes.
f. Click OAuth Client (1.0). Note down the ID and Secret that are generated.
4. ACL Permission to Client
Provide Permission to client application by adding it to the Administrators group.
a. Navigate to Security > User Management
b. Under Groups, select the group Administrator (by default Administrators is selected)
c. The client id is present in the Remaining Users section,
d. Move the client ID under Users in this Group.
e. Click Save Changes.
5. Create Scope and associate with client
a. Navigate to Security >OAuth.
b. Click Scope Management.
c. Click Add Scope.
d. Provide the following information:
Name:
View Description:
Read only access scope Folders and services:
example.com Click
Associate Scopes to Client.
Select
OAuth Client(1.0) in the
Remaining Clients section and move it to the
Clients associated with Scope section.
Click
Save Changes.
Step2: Configure remote Integration Server authorization server in API Gateway
Configure the remote Integration Server as an external authorization server in API Gateway.
1. Navigate to Menu >Administration
2. Click Security > JWT/OAuth/OpenID
3. Click External authorization servers > Add authorization server.
4. Provide the following:
Name:
IS_OAuthServer Description (optional): I
ntegration Server acting as Authorization server 5. Click Introspection.
You use Introspection to authenticate the token. It happens ollows
Local introspection. Validating the token within the gateway. This is done using the JWKS URI or the public certificate of the issuer. In this case the token should necessarily be JWT.
Remote introspection. Validating the token with the authorization server. It has introspection endpoint, which is used to validate the token. In addition, the client id and client secret are used to protect the endpoint, so that anonymous users cannot access to the resource. To invoke an endpoint you require a user; Gateway user is the one you cam use to invoke the endpoint. There is no support for token caching in remote introspection.
6. Provide the following in the Remote introspection section
Introspection endpoint:
http://{7BIntegrationserver_machinename}:5555/invoke/pub.oauth/introspectToken Gateway user:
Administrator Client ID and
Secret: Use ID and secret noted down earlier.
7. Create Scopes in External Authorization servers page
Click
Scopes under
Add authorization server Create Scope similar to the one in Integration Server.
Provide the Scope:
ViewProvide Description:
Scope created similar to IS ScopeClick
AddIntegration Server should be listed in External authorization servers
Step 3: Create an API with strategy
In this example you create an API by importing from the URL https://petstore.swagger.io/v2/swagger.json, enforce it with OAuth2 policy, and create an applicatin with strategy and associate it with the API. .
1. In the APIs tab click Create API.
2. Select Import API from URL.
3. Provide the following information.
URL:
https://petstore.swagger.io/v2/swagger.json Name:
RestOps Type:
Swagger Version:
1.0 4. Click Create. The API is created and the API details page for the API appears.
5. Create an Application with Strategy
For creating an Application, follow the below steps.
a. Click Applications in the title navigation bar.
b. Click Create application provide the Name: API Application
c. Click Continue to Identifiers.
In this use case, no details are provided for the Identifier page.
d. Search the API RestOps, by typing RestOps in the Find APIs text box.
The RestOps API appears in the Selected APIs section.
e. Select the RestOpsAPI.
f. Click Continue to Advanced.
g. Click Continue to Authentication .
h. Click Create Strategy . A strategy is a way to authenticate the incoming request and provides multiple authentication mechanisms or multiple authorization servers for a single authentication scheme. One can create multiple strategies authorized by an API for an application.
i. Provide the Name: AppStrategy.
j. ClickAdd
k. Click Save
6. Enforcing OAUTH2 policy on the API
Enforce OAuth2 policy to the created API . This policy ascertains that an OAuth token is required to access this API..
a. Click API in the title Navigation Panel.
b. Click RestOps.
c. Click Policies tab.
d. Click Edit
e. ClickIdentify & Access from the Policy catalog.
f. Select the identification type as OAuth2 Token and Save.
g. The API can be Activated, or can navigate to the APIs in the title navigation bar and Activate.
Step 4: Mapping OAuth scopes
Now map the scope that was defined in the Authorization server with the APIs in API Gateway to authorize the access tokens to be used to access the protected resources. One can map either a complete API or parts (resources or methods) of an API to the scope or can add the scope details and modify the scope details as required from the OAuth/OpenID scopes page.
1. Expand the menu options in the title bar and Select OAuth/OpenID scopes.
2. Click Map scope.
3. TypeIS_OAuthServer in Select authorization server scope and select the listed Authorization server scope from the search list populated.
4. Click API scopes.
5. Type RestOps API Scope, which is to be linked to the authorization server, in API scopes search text box.
6. Save the changes. This maps the authorization server scope to the selected API scopes and lists the authorization scope in the scopes list.
Step 5: Get authorization code
1. To get the Authorization code copy the client ID from the Integration server as seen in above step 1.
2. Access the Authorization code using below URL. https://<machinename_remoteintegrationserver>:5555/invoke/pub.oauth/authorize?client_id= f2c86e721b0344b0a076834449ae70a9&redirect_uri=http://example.com/redirect&response_type=code&state=121
3. Click Approve
4. Copy the authorization code from the URL. http://example.com/redirect?code=4a609ffc126343ae841237c0428bf0f9&grant_type=authorization_code&redirect_uri=http%253A%252F%252Fexample.com%252Fredirect&state=121&scope=ViewCopy the authorization code from the URL.
You might get an error, but the authorization code is present in the URL as you are providing dummy redirect URI.
Step 6: Getting the access token
To get the access token, follow the below steps.
1. Open Postman or any other Rest Client
2. Copy the code from the above step
3. Make a POST call to the following URL, with the hostname of the system, where API Gateway is installed in place of localhost and use external port instead of default port like below. https://<machinename_integrationserver>:5555 /invoke/pub.oauth/getToken
4. In the Body provide the following Request payload:
{
"code":"4a609ffc126343ae841237c0428bf0f9",
"redirect_uri":"http://example.com/redirect",
"grant_type":"authorization_code",
"scope":"View"
}
5. In the Authorization select Basic Auth and provide the client_id in the Username and client_secret in the password.
6. The output is the access_token, refresh_token and token_type
Step 7: Invoke API
The access_token can be used to invoke the API
1. Navigate to APIs in the title menu
2. Click RestOps
3. Under Technical information copy the Gateway endpoints
4. Have a look into the Resources and methods. You can use invoke any of these.
5. In PostMan invoke the API using the Gateway endpoints with the required resource or method.
6. In Authorization provide select Bearer token and provide the access_token
Alternative/Exception Flows
The same use case can be done with Client Credentials as well.
You can get the access token using client credentials. You require the client_id and client_secret.
1. Open Postman or any other Rest Client
2. Make a POST call to the following URL, with the hostname of the system where API Gateway is installed in place of localhost and use external port instead of default port as follows: https://<machinename_remoteintegrationserver>:5555 /invoke/pub.oauth/getToken
3. In the Headers provide Content-Type asapplication/json (if not specified).
4. In the Body provide the following Request payload:
{
“client_id”:”xxxxx”,
“client_secret”:”xxxxx”,
“ grant_type”:”client_credentials”
}
5. The output gives you the access token.
6. Use the access token to invoke the API.
