Author: Naramsetty, Srikar <Srikar.Naramsetty@softwareag.com>
Supported Versions: 10.3 and above
webMethods API Gateway tutorial
Overview of the tutorial
This tutorial helps to understand how a third party OAuth 2 identity provider and authorization server can be configured in API Gateway to secure the APIs using OAuth 2 authorization. Some of the providers who already provide this support are OKTA and PingFederate. In this case the API Gateway still remains as the Resource server. In this tutorial we will use OKTA as our OAuth 2 identity provider and go through the following steps in detail.
- Configuring OKTA as OAuth2 Provider
- Obtaining a token from OKTA
- Creating an auhtorization server namespace in OKTA
- Obtaining Metadata URI and endpoints from OKTA
- Configuring OKTA third-party OAuth 2 provider in API Gateway
- Configuring OKTA third-party OAuth 2 authorization server in API Gateway
- Creating a consumer application in API Gateway
- Configuring external authorization server in Integration Server
- Invoking the OAuth 2 protected API using postman client
Required knowledge
The tutorial assumes the reader has:
- a basic understanding of API Gateway and its policy enforcement
- a basic knowledge on OAuth 2 authentication framework
Why?
While the API Gateway provides out of the box support for the built in OAuth 2 authorization server (the one which is provided by the Integration Server) there are some customers out there who already have authorization servers existing in their production environment. They are bound to use only the authorization server which comes along with the product and this makes them restricted to not use their servers. Hence to help the existing customer base to use their existing OAuth 2 provider, the API Gateway provides support for the configuration and usage of third party OAuth 2 identity providers to secure the APIs using OAuth 2.
Prerequisite steps
Complete the below prerequisites to make you ready to get into the details of the Third party OAuth 2 identity provider support in API Gateway.
- Create a tenant account in OKTA identity provider management portal
- Install postman REST client of version >= v6.0.10
- Import the attached archive
Details
Step 1: Configuring OKTA as OAuth 2 Provider
Token creation
First and foremost thing of this tutorial is to create a token in the OKTA tenant account to access all the OKTA endpoints from API Gateway. This token acts as a authentication that only the valid user is accessing the endpoints.
Login into OKTA and Go to API → Tokens
Click on Create Token, give a name and submit. Save the token for future use since that will be the only time you will be viewing it.
Authorization server creation
The next thing is to create an authorization server namesapce in OKTA.
Go to API → Authorization Servers
Click Add Authorization Server and provide the Name, Audience and Description and Save.
Obtaining Metadata endpoints from OKTA
The Metadata endpoints for Client registration, Client Update, Scope creation, etc at the third party OAuth authorization server can be obtained by accessing the Metadata URI.
Select the Authorization server and find the Metadata URI in the Settings.
Invoke the Metadata URI from the the browser and you will get all the endpoint URLs in the response.
Step 2: Configuring OKTA OAuth 2 provider in API Gateway
Not every identity provider aligns to the OAuth2 spec, If the provider deviates slightly from the actual spec. You can provide the deviation specification, so that we can handle the requests internally. API Gateway comes with the predefined providers OKTA and PingFederate in the Third party OAuth 2 configuration. You can also create your own identity providers by following the below steps:
Go to Adminitration → Security → JWT/OAuth/OpenID → Providers. Click Add provider and provide the details. This provider configuration is used in the Dynamic client registration.
Client metadata field mappings are the deviations the OAuth2 provider deviates from the actual specification. Extended request parameters are the additional headers that needs to be sent while invoking the corresponding request.
For the tutorial purpose we can take the predefined provider OKTA as our identity provider. OKTA completely aligns with the actual spec, so there are no details provided.
Step 3: Configuring OKTA OAuth 2 authorization server in API Gateway
Now that the provider is available. The next thing is to create the authorization server alias in API Gateway for the OKTA authorization server we created in Step 1. The API Gateway uses this alias to register a client with OKTA authorization server. The below steps provide how to create an authorization server alias in API Gateway:
Go to Adminitration → Security → JWT/OAuth/OpenID. Click Add authorization server.
You can provide the metadata/ well known URI which we got in the Step1 and provide it in the Discovery URL and click on Discover. All the necessary fields which are present in the well known URI will be fetched and the fields will be auto populated.
Authorization server configuration is divided into 5 parts:
1. Introspection
Introspection is the way to authenticate the token. It is sub divided into 2 parts
- a. Local introspection: Validating the token with in the gateway. This can be done using the JWKS URI or the public certificate of the issuer. For this the token should necessarily be JWT.
- b. Remote introspection: Validating the token with the authorization server. It has introspection endpoint, which is used to validate the token. Along with that we have client id and client secret which we are used to protect the endpoint, so that anonymous users wont get access to the resource. Underneath to invoke an endpoint we need a user, Gateway user is the one under which we invoke the endpoint.
OKTA issues tokens as JWT, so just the issuer and JWKS uri are enough to validate the token. And these are populated directly using the well known URI
2. Dynamic client registration
Dynamic client registration is used when you want to create the client automatically in the OAuth2 authorization server when a application is created in API Gateway.
All the details are auto populated except the authentication details. You need to manually provide the authentication details.
3. SSL Configuration
If you want a 2 way SSL then provide the SSL Configuration
4. Metadata
Metadata are the URLs to get the access tokens. These urls are used for the API Portal. These are also pre-populated using the well known uri
5. Scopes
Scopes are the ways to limit access to a protected resource. Refer to Security unhashed - Introduction to OAuth2 for more details on the scope. These scopes are also auto populated using the well known uri. If you want to add any additional scope you can add them manually. But make sure the scope is created in the authorization server. API Gateway doesn't deal with creating/managing the scopes in the authorization server.
To create the scopes in OKTA go to API → Authorization Servers → Your authorization server → scopes → Add scope.
For our example lets say my company provides resource about the travel. So I create 3 business scopes (view to view the booked tickets, book to book any new tickets, cancel to cancel the booked tickets) in authorization server.
So if you have a well known/metadata URI, all you need to provide is the authentication details for the Dynamic client registration. All other fields are auto populated.
Once the authorization server is added you can test if the provided details are proper. Click on the tick button to test the authorization server.
Step 4: Creating API with OAuth policy enabled
Go to Policies → Identify & Access → enable OAuth2 token.
Also create the API Scopes, Here I have created View ticket with all get resources, BookTikcets with Post resources and Cancel tickets with delete resources.
Step 5: Creating scope mapping in API Gateway
Now there are multiple scope available for the authorization server. Like view, book, cancel..etc. We need to provide a meaning for those scopes in API Gateway, what resources that a scope can have access to. Go to OAuth/OpenID scopes under main menu. Here in this we need to map which authorization scope should have access to which APIs/ API Scopes.
Step 6: Creating a consumer application in API Gateway
Now lets create an application in API Gateway. Go to Applications. Click on Create application button, provide the name, Associate the API and go to Authentication. Click on Create Strategy. Provide the name, description and then select the Authorization server which we have already created.
Generate credentials: This will be shown only when "Enabled" button was turned on for Dynamic client registration in the external authorization server.
- If the client already exists in the authorization server and if you want to map that client to the application in gateway. Then keep the generate credentials off and provide the Client ID. This way we map this client to the application. If the token issued by Authorization server is generated by shared secret. Then you can enable the HMAC algo and provide the secret.
- If you want to create a client then turn on generate credentials and provide the necessary fields. Grant types and the scopes are fetched from the authorization server.
When you click on Add, API Gateway invokes the Client registration endpoint in the OKTA authorization server (which we created in Step 1) and a client is created in OKTA. Then the Gateway retrieves the Client ID, Client secret, Scopes and other OAuth 2 related client registration details from the OKTA server and saves them in the Strategy and associate the strategyId to the application.
Create PKCE client
From the OKTA doc, if the Application type is Public and the Application profile is Native then it will create a PKCE client.
Once the strategy is created. Save the application and you can see the details of the strategy you have created.
Step 7: Invoking the OAuth 2 protected API using postman client
API Invocation
Now we can invoke the OAuth 2 protected API using the postman client by following the below steps.
Obtaining access token from OKTA server
In the postman create a request for the API with OAuth 2.0 selected in the Authorization section and click Get New Access Token.
You will get a screen like below.
Enter all the relevant details such as Auth URL, Access Token URL, Client ID, Client Secret and Scope which we obtained from the OKTA Metadata URI and API Gateway consumer application and click Request Token button. You will get the OAuth 2 access token as below.
Click on Use Token and click Send to send the request to API Gateway API. The OAuth 2 access token is added as a Bearer token in the Authorization header in the request and sent to the API. A successful response (200 OK) is received from the API.
Now we accessed an OAuth 2 protected API with the use of a third party OAuth 2 provider support in API Gateway.
Step 8: Using request transformation policy
The values inside the token can be used for further processing using the request transformation policy. Look at Request and Response Transformation policies in API Gateway
${request.authorization.clientId}
|
request
|
authorization |
clientId |
|
issuer |
||
|
userName |
||
|
authHeader |
||
|
incomingToken |
||
|
audience |
||
|
claims.CLAIM_NAME |
Remote IS as external authorization server
You can configure Remote IS as an external authorization server. But it doesn't support the Dynamic client registration. Instead you can configure the client directly in the remote authorization server and configure API Gateway to accept the tokens from that client.
Go to Administration-> Security-> JWT/OAuth/OpenID
- Click on Add new authorization server, provide any name
- Introspection → Remote introspection, Configure URL : <<Remote IS host: port>>/invoke/pub.oauth/introspectToken
- Gateway user : Any valid user of Gateway
- ClientID : Active client id from the remote IS
- Client Secret: Client secret of the respective client.
- Add the scopes that are available in the remote authorization server under Scopes
- provide Scopes to API mapping under main menu OAuth/OpenID scopes.
- Create an application → Go to authentication → create a strategy with the configured remote authorization server and the client-id for this application.
- Get the token for the client from remote authorization server. Below are the URLs
-
Type
URL
Authorize https://<IS_HOST>:<IS_PORT>/invoke/pub.apigateway.oauth2/authorize
Access token https://<IS_HOST>:<IS_PORT>/invoke/pub.apigateway.oauth2/getAccessToken
Refresh token https://<IS_HOST>:<IS_PORT>/invoke/pub.oauth/refreshAccessToken - Invoke the API by passing it as a bearer token
Using OAuth in Microgateway
OAuth policy can be configured in Microgateway from version 10.4. The administration settings for JWT can be configured in Microgateway either by copying settings from API Gateway server or by provisioning the values in YAML file during startup.
Authorization servers
Download Settings from API Gateway
Configure api_gateway → download_settings property as "true" in the YAML file to download the settings of API Gateway and use them in Microgateway. This helps to download the settings under Administration → JWT/Oauth/OpenID into Microgateway.
downloadSettings.yml
ports:
http: 4485
https: 7749
api_gateway:
url: "http://localhost:5555"
user: "Administrator"
password: "{encoded}bWFuYWdl"
dir: "C:/Installations"
download_settings: true
...Configure using YAML file
Configure the security_settings as provided in this file microgateway_jwt_oauth_openid.yml.
What changed from 10.2
- We are not managing the scopes from Gateway. Scopes needs to be created manually in the authorization server and only be used while creating the application
- There is no active authorization server. Now the DCR can be done with any of the configured authorization servers.
- Application creation won't create the OAuth credentials by default. Not every consumer might need the OAuth, so its upto the consumer whether he needs OAuth. If consumer wants OAuth he can create it using the strategy in application
- Scope to resource mapping should be done manually by Administrator/Provider in gateway
- From 10.3 we support the local introspection of the OAuth tokens
Limitations
Below are the limitations for the third party OAuth 2 provider support in API Gateway.
- API Gateway 10.3 supports only OAuth 2.0
- OAuth 2 is not supported for WebSocket API
- The third-party vendor of the authorization server should support RFC 7662, OAuth 2.0 Token Introspection
References
Troubleshooting
|
#
|
Issue
|
Solution
|
|---|---|---|
|
#
|
Issue
|
Solution
|
| 1 |
This problem occurs because the ACL is not assigned to the OKTA application (Client registration) in the OKTA authorization server. This can be solved by assigning an access control group to that application,. Go to Applications in the OKTA portal and select the OKTA application that was created as part of the API Gateway application creation. Click Assign and select Assign to Groups. Assign Everyone and click Done.
|
|
| 2 |
This problem occurs because there was no Access policy and a rule configured in the OKTA authorization server space. This can be solved by creating an Access policy and a rule in the OKTA authorization server details. Go to API → Authorization Servers and select the Authorization server. Go to Access Policies and add a policy and a rule.
|
|
| 3 |
In the GET NEW ACCESS TOKEN window of the postman client select "Send client credentials in body" in the Client Authentication.
|
|
| 4 |
If you get token is invalid or expired
|
|
Downloadable artifacts
Learn more
- For securing APIs using OAuth 2 in API Gateway for versions 10.3 and above please refer http://techcommunity.softwareag.com/pwiki/-/wiki/Main/Securing+APIs+using+OAuth+2+in+API+Gateway
- For securing APIs using OAuth2 in API Gateway for versions below 10.3 please refer http://techcommunity.softwareag.com/pwiki/-/wiki/Main/Securing+APIs+using+OAuth2+in+API+Gateway
- For securing APIs using thirdparty OAuth2 identity provider in API Gateway for versions below 10.3 please refer http://techcommunity.softwareag.com/pwiki/-/wiki/Main/Securing+APIs+using+thirdparty+OAuth2+identity+provider+in+API+Gateway
- For securing APIs using JSON Web Token in API Gateway for versions 10.3 and above please refer http://techcommunity.softwareag.com/pwiki/-/wiki/Main/Securing+APIs+using+JSON+Web+Token+in+API+Gateway
Time travels.zip (18.7 KB)
