This article describes the configuration needed to use a third-party OAuth authorization server with webMethods Integration Server. The article uses Okta, an OAuth vendor, to illustrate the steps you need to take. Similar configuration will be required for other OAuth vendors.
Integration Server 10.1 adds support for OAuth 2.0 token introspection. This feature allows clients, when Integration Server is an OAuth resource server, to use access tokens issued by third-party OAuth authorization servers. It also exposes an OAuth token introspection endpoint that complies with the OAuth standard. This allows clients to use tokens issued by an IS OAuth authorization server to access resources on a third-party OAuth resource server.
In addition to token introspection, Integration Server 10.1 adds support for OAuth 2.0 token revocation. This feature exposes an OAuth token revocation endpoint that complies with the OAuth standard. This allows clients and administrators to remove previously issued access tokens so they may no longer be used to access protected resources.
The standards documents that relate to these features are
- RFC 6749 – The OAuth 2.0 Authorization Framework
- RFC 7662 – OAuth 2.0 Token Introspection
- RFC 7009 - OAuth 2.0 Token Revocation
This document provides an informal description of the steps needed to configure Integration Server and Okta, a third-party OAuth authorization server, so that clients can use Okta-generated access token to access protected resources in Integration Server.
Setting up Okta
Okta makes their OAuth offering available to developers as an online service rather than an installable server.
Get a developer account. Go to https://developer.okta.com/signup/ to create a developer account. You will be assigned a domain which you'll use when administering and testing your OAuth applications with Okta.
Log in to Okta with your account.
Create an API token. Go to Admin > Security > API and click the Create Token button. Make note of your API token because it will not be shown to you again. You'll need to include it in the API calls used to build your test environment.
Create an authorization server. Go to Admin > Security > API to create an authorization server. Follow the steps in http://developer.okta.com/docs/how-to/set-up-auth-server.html. Your authorization server will be assigned an ID which you'll use in the URLs of subsequent API calls.
Create scopes. Any OAuth scopes that you plan to use in your testing will need to be added to your Okta authorization server. Go to Admin > Security > API and click the name of the authorization server. Click the Scopes link. Click the Add Scope button. The scope must have the same name in the Okta authorization server as it does in the IS resource server. Click the Create button to save the scope for this authorization server.
Note: You can find the URLs for all your OAuth endpoints (and other OAuth and OpenID Connect information) at https://<your-okta-domain>/oauth2/<your-authorizationServerId>/.well-known/openid-configuration, where <your-okta-domain> is the domain name assigned to you when you created your developer account and <your-authorizationServerId> is the ID for your authorization server. The output is unformatted JSON, which is hard to read. You can copy the response and paste it into an online JSON formatter, such as https://jsonformatter.curiousconcept.com/
Get Postman. At this point, you'll need to use the Okta API to create and maintain clients, request authorization, get authorization codes and access tokens. The easiest way to do this is to use Postman, a Chrome application. Okta provides Postman collections, sets of pre-coded calls to their APIs with variables for you to plug in values specific to your Okta environment. Download Postman here: https://www.getpostman.com/apps. The free version works fine.
Install Okta’s Postman collections. You will need two of the Okta Postman collections: Client Registration and API Access Management. To download into your installed Postman app, click the Run in Postman buttons for these two collections at https://developer.okta.com/docs/api/getting_started/api_test_client.html#collections-quick-reference.
Client Registration API can be found at https://developer.okta.com/docs/reference/postman-collections/.
Set an Okta environment. After the Postman app and Chrome extension are installed, set up Postman to work with your Okta account and authorization server. Click on the Settings button (the gear) in the upper right and create a new environment. Select it from the drop-down and click the Quick Look button (the eye) to view it.
Click the Edit link and supply values for
- uri: https://<your-okta-domain>
- apikey: the API token value described above
Scroll to the bottom of the environment window and add names/values for
- redirectUri: the URI of your client application’s redirection endpoint
- authorizationServerId: the ID for your Okta authorization server
- scopes: if using multiple scopes, separate them with a space
Make sure the spelling and the case are correct. These values are substituted for variables in the Okta collections.
Create a client in your authorization server. To create a new client, click the Client Registration API collection to open it. Select Create Client. The request to create a client will appear on the right half of the Postman window. Click the Headers and Body subheadings to view the request. Note that URL and headers contain variables that will be substituted before the API call is transmitted. The variable names are surrounded by double curly braces, like {{uri}}. The values for these variables come from the currently selected environment. If your environment is missing a variable that is used in the request, the variable will appear in red. All variables that have a corresponding value in the environment appear in orange.
Click the Send button to transmit the request. If it succeeded, the response will contain a JSON document with details about the new client, including clientId and clientSecret.
Make note of the clientSecret as it will not be shown to you again. If you plan to test in Postman with this client, go to your environment and add
- clientID
- clientSecret
If you need a new client secret, use the Generate New Client Secret call from the Client Registration API collection.
Setting up Integration Server
Create scopes. Go to Security > OAuth > Scope Management > Add Scope to create the scopes you’ll use in your testing. Specify a folder or service for each scope.
Create an External Authorization Server for Okta. Go to Security > OAuth and click the Add External Authorization Server link. Enter values in these fields:
Name: Okta
Introspection Endpoint:
https://<your-okta-domain>/oauth2/<your-okta-authorizationServerId>/v1/introspect
Client Id: ID of you test client
Client Secret: Secret of your test client
User: IS user account to use when invoking services on behalf of the test client
Set Okta as IS’s authorization server. Go to Security > OAuth and click the Edit Global Settings link. Under Resource Server Settings, open the Authorization Server drop-down and select Okta.
Create a redirection endpoint service. The redirection endpoint may be hosted by any server capable of receiving and sending HTTPS requests. We will use Integration Server. The URL to access the redirection endpoint service is what you specify as the redirectUri for your test client in the Okta authorization server. Here is an example of what a redirection endpoint service might do in the OAuth Authorization Code Grant.
INVOKE pub.flow:tracePipeline
Writes the inputs, sent from the authorization server, to the server log. May be helpful for debugging.
MAP (Set Okta-specific values for OAuth variables.)
redirect_uri: the client’s redirection endpoint uri
scope: the scope for this test (space separated)
client_id: ID of client used for this test
client_secret: secret of client used for this test
INVOKE pub.client:http
url: your authorization server’s token endpoint
method: post
loadAs: bytes
data/table: code = %code%
grant_type = authorization_code
redirect_uri = %redirect_uri%
auth: type = basic
user = %client_id%
pass = %client_secret%
headers: Content-type = application/json
[Select Perform variable substitution.]
INVOKE pub.string:bytesToString
Map body/bytes to bytes
MAP drop unnecessary variables
The output pipeline will contain a JSON string with the access_token and refresh_token, if one was returned.
Getting an Access Token
OAuth’s Authorization Code Grant involves human interaction through a browser. Enter this request in your browser’s address field (line breaks added for readability):
https://<your-okta-domain>/oauth2/<your-authorization-server-id>/v1/authorize?
client_id=<your-client-id>&
response_type=code&
response_mode=query&
scope=<your-scope>&
redirect_uri=<your-redirection-uri>&
state=<an-arbitrary-state-value>&
nonce=<an-arbitrary-nonce-value>
You will be prompted to approve or deny the request for authorization from your testing client.
If you approve the client request and the Okta authorization server does not find any problems with it (such as invalid or missing parameters), the server will respond with an authorization code and redirect your browser to the client’s redirection endpoint. What happens next depends on what the redirection endpoint does. For the authorization code grant, the endpoint should call the authorization server’s token endpoint, passing the authorization code. It will get an access token in response.
Using an Access Token
Use the access token. To use an Okta access token, issue a request to Integration Server with the access token in the request header.
Using cURL, a popular command-line HTTP client, it looks like this:
curl -v "http://localhost:5555/invoke/pub.math/randomDouble" -H "Authorization: Bearer <access-token-value>"
Integration Server will send a request to the Okta authorization server’s introspection endpoint to check that the supplied access token is valid. If so, and the requested service is in the scope that the token was issued for, the service will be executed and the response returned. If the token is invalid or the request is not in the token’s scope, a 401 status code will be returned.
Revoking an Access Token
To thoroughly test token introspection with IS and Okta, you will want to verify that you cannot access a protected resource with a token that has been revoked. Use Okta’s token revocation endpoint. An authorization server’s revocation endpoint accepts HTTP basic authentication. You will need to prepare a value that can be passed as credentials in the HTTP Authorization request header.
- Go to an online Base64 encoder such as https://www.base64encode.org/.
- Enter <your-clientId>:<your-clientSecret> and Base64-encode it.
- Copy the resulting string to your clipboard. This is your Base64-encoded credentials.
Go to Postman and open the API Access Management collection. Select the Revoke Token call.
- Click on the Headers subheading. In the Authorization field, enter
Bearer <base64encoded-credentials>
- Note that there is a space between “Bearer” and the Base64-encoded string.
- You must use the Id and Secret of the client the token was issued to.
- Click on the Body subheading
- enter a valid token value in the token field.
- The token_type_hint field is optional. It can be left empty or set to “access_token” or “refresh_token”.
- Click Send to transmit the request. You should get a “200 OK” response.