Securing APIs Using OAUTH 2.0 In API Gateway Using External Ports
This use case defines OAuth2.0 authentication protocol that identifies and authorizes a client application using external ports. In API Gateway OAuth2.0, you can configure services using both primary and external ports. When you do not want to expose the primary port to the outside world, you can configure an external port. This external port is exposed to the outside world for allowing users to consume the APIs.
This use case explains, with a simple example, how to secure an API with OAuth2 authentication using external ports. This example uses Client Credentials as the grant type and a single instance of API Gateway 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 on webMethods
API Gateway,
Integration Server, OAuth2 architecture.
Before you begin
Ensure that you have:
Installed
Integration Server with
API Gateway.
Knowledge about 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 external port
1. Enable OAuth 2 authorization through HTTP in API Gateway.
To enable API Gateway to accept request through HTTP, you must set the value of pg_oauth2_isHTTPS to false as follows.
a. Expand the menu options in the title bar and select Administration.
b. Select General > Extended settings.
c. Click Show and hide keys.
This displays all the configurable parameters.
d. Set the value of pg_oauth2_isHTTPS to false.
e. Click Save.
2. Enable OAuth 2 service using the external port.
For the OAuth service to be available through external ports, set the value of watt.server.revInvoke.proxyMapUserCerts property to true as follows. The default value of this property is false.
a. Expand the menu options in the title bar and select Administration.
b. Select General > Extended Settings.
c. Click Show and hide keys.
This displays all the configurable parameters.
d. Set the value of watt.server.revInvoke.proxyMapUserCerts property to true.
e. Click Save.
3. Create external and registration ports in API Gateway.
The external client requests come to an external port, which delegates the request to its paired port, that is the registration port.
a. Expand the menu options in the title bar and select Administration.
b. Select Security > Ports and click on Add Ports.
c. Select the type of port as API Gateway external and click Add.
d. Provide the following information:
External port:
1234 Alias:
ExtPort e. Under API Gateway registration listener configuration, provide the following information:
Registration port:
4567 Alias:
RegPort f. Click Add.
g. Click Add button at the end of the page to add the external port.
4. Create an internal port on API Gateway.
In this use case, a single API Gateway instance is used. In the case of creating an internal port in the internal server, the same API Gateway server acts as an internal server, which listens and pulls the requests queuing up in the registration port.
a. Expand the menu options in the title bar and select Administration.
b. Select Security > Ports.
c. Click on Add Ports and select API Gateway internal and click Add.
d. Provide the following value for Alias, IntPort.
e. Under API Gateway external server, provide the following information:
Host:
127.0.0.1 Port:
4567 f. Under Registration credential(optional), type the username as Administrator and password as manage.
g. Click Add.
5. Enable the ports.
Enable the ports after all the ports are created. Click on the x under Enabled column for the ports.
Step 2: Configure API Gateway as an internal authorization server
Here, you configure API Gateway with the required information to act as an internal authorization server for OAuth or JWT depending on what authentication protocol you want to use to identify and authorize a client application. You can also define the required scopes that provide a way to limit the amount of access that is granted to an access token. In this xample, use the default configuration as it is and define one OAuth Scope (OAuth2Scopes) to limit the resource usage.
1. Expand the menu options in the title bar and select Administration.
2. Select Security -> JWT/OAuth/OpenID and click local.
This displays all the configurable settings for the Authorization Server.
3. Click OAuth scopes to add Scope.
4. Provide the following information and click Add:
Scope:
OAuth2Scopes Scope description:
Validate OAuth 2.0 Scopes 5. Click Update.
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.
1. In the APIs tab, click Create API.
2. Select Import API from URL.
3. Provide the following details.
Name:
RestOps Type:
Swagger Version:
1.0 4. Click Create.
The API is created and the API details page for the API appears.
5. Enforce OAuth 2 policy on the API.
You enforce OAuth2 policy on the RestOps 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 the Policies tab.
d. Click on Edit to add the policy to API.
e. Click Identify & Access in the Policy catalog.
f. Select the OAuth2 Token check box in the Identification Type field of the Application Identification section and save the changes.
g. Click Activate to activate the API on the API details page of the API.
6. Create an Application in API Gateway with strategy and register it to an API.
a. Click Applications in the title navigation bar.
b. Click Create application.
c. Provide the name as APIApplication.
d. Click Continue to Identifiers.
e. Click on Continue to APIs.
f. Search the API RestOps, by typing RestOps in the Find APIs text box.
The RestOps API appears in the Selected APIs section.
g. Select the RestOpsAPI.
h. Click Continue to Advanced.
i. Click Continue to Authentication.
j. Click Create strategy.
A strategy is a way to authenticate the incoming request and provide multiple authentication mechanisms or multiple authorization servers for a single authentication scheme. You can create multiple strategies authorized by an API for an application.
k. Provide the name as AppStrategy.
l. Enable the toggle button Generate credentials to generate the credentials dynamically in the authorization server.
The client-id and client-secret get created automatically.
m. Select Confidential from the Application type drop-down list.
n. Specify the redirect URIs that the authorization server can use to redirect the resource owner's browser during the grant process. In this example, provide www.example.com, which is not a valid URL.
o. Select the required Grant types. In this example, the selected grant types are authorization_code and client_credentials.
p. Provide OAuth2Scopes in the Scope text box and click the search icon.
The matching OAuth2Scopes appear.
q. Click + sign to add the scope to the Strategy.
r. Click Add button at the bottom to add the Strategy.
s. Click Save.
Step 4: Map OAuth scopes
After registering an application, you must map the scope defined in the Authorization server with the APIs in API Gateway to authorize the access tokens to be used to access the protected resources. You can map either a complete API or parts (resources or methods) of an API to the scope or add the scope details and modify the scope details as required from the OAuth or OpenID scopes page. In this example you select the OAuth2Scopes scope.
1. Expand the menu options in the title bar and select OAuth/OpenID scopes.
2. Click Map scope.
3. Type OAuth2Scopes in Select authorization server scope and select the listed Authorization server scope from the search list populated.
4. Click API scopes.
5. Type RestOps or API Scope, which is to be linked to the authorization server, in API scopes search text box.
6. Click Save.
The authorization server scope is mapped to the selected API scopes and the authorization scope is listed in the scopes list.
Step 5: Get authorization code
As the grant type chosen is Client credentials, the Client Id and Client secret is required to get the bearer token.
1. In the title bar, click on Application.
2. Click the Application APIApplication.
3. Click AppStrategy.
4. Note the Client id and Client secret.
Step 6: Get the bearer token
Get the OAuth bearer token using external ports.
1. Use any Rest client to retrieve the token.
In the following example, Postman client is used.
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.
http://machinename:1234 /invoke/pub.apigateway.oauth2/getAccessToken
http://localhost:1234 /invoke/pub.apigateway.oauth2/getAccessToken
3. Provide the following payload, with the required client id and client secret and grant type, in the body of the request section. In headers, provide Content-Type as application/json (if not specified).
The access token that can be used to access the required application is displayed in the response section.
Step 7: Invoke API
Invoke API using the bearer token. Add the OAuth2 access token as a Bearer token in the request header and send to the API. A successful response, 200 OK is received from the API with the desired response.
The response is as shown.
