OAuth 2.0

What is OAuth 2.0?

The OAuth 2.0 Authorization Framework facilitates the sharing of private resources (data or services) with a third-party client application (client). In an OAuth session, private resources are stored on a resource server and the owner of the resources, or resource owner, grants the client application permission to access them.

The resource owner is typically a person; however, in some cases it could be an application. When a resource owner grants permission, the OAuth authorization server issues an access token to the client application. When the client application passes the access token to the resource server, the resource server communicates with the authorization server to validate the token and, if valid, provides access to the resources.

The following example illustrates the roles involved with an OAuth session. In the example, Bob is the resource owner who wants to access and print his photos stored on the PhotoStorage website (the resource server) using the PhotoPrint service (the client application). PhotoPrint supplies Bob with an application that runs on his device (phone or laptop). Bob uses that application to initiate the process. PhotoPrint sends a request to the PhotoStorage authorization server. The authorization server requests authorization from Bob and issues a token to PhotoPrint. PhotoPrint can then access Bob’s photos on PhotoStorage.

Configuring OAuth 2.0

IBM webMethods Integration services can be accessed through REST APIs from any REST client. In OAuth 2.0, the client obtains an access token issued by an authorization server on approval of the resource owner. The client uses the access token to access the protected resources.

An in-depth description of OAuth is beyond the scope of this document but is available elsewhere. For information about the OAuth protocol, see the OAuth 2.0 Authorization Framework.

Before you invoke services using OAuth 2.0 tokens, you must define clients, scopes, associate scopes to clients, and generate OAuth 2.0 tokens. The following table describes how to configure OAuth 2.0.

Registering Clients

Before a client can request access to a protected resource, it should register with IBM webMethods Integration. When you register a client, you identify the client as a confidential client or a public client, select the grant types the client can use, and specify the token expiration and refresh information. The Client Registration page lists the clients registered with IBM webMethods Integration.

Adding Clients

1. From the IBM webMethods Integration navigation bar, click on the profile icon located at the top-right corner of the home screen and select Settings > OAuth 2.0 > Client Registration > Add New Client.

   

   

2. On the Add New Client dialog box, complete the following fields. Required fields are marked with an asterisk on the screen.

   Field	Description
   Name	Type the name of the client. You cannot create clients with the same Name and Version combination. You cannot modify the client name after the client is saved. Client names are not case-sensitive.
   Description	Type a description of the client.
   Client ID	The Client ID field appears only when you update a client. This is a client identifier issued to the client to identify itself to the authorization server, and is used while generating tokens.
   Client Secret	The Client Secret field appears only when you update a client. This is a secret matching to the client identifier and is used while generating tokens. It will not be generated if the Client Type is Public.
   Authorization Endpoint	View the authorization URL that has to be provided while generating tokens. See the Generating Tokens section for more information.
   Token Endpoint	View the Access Token URL that has to be provided while generating tokens. See the Generating Tokens section for more information.
   Refresh Token Endpoint	View the Refresh Token URL that has to be provided while refreshing Access Tokens. See the Refreshing Access Tokens Using Refresh Tokens section for more information.
   Version	Type the version number of the client. You cannot create clients with the same Name and Version combination.
   Type	Select the type of the client according to its ability to communicate with IBM webMethods Integration. Confidential Select Confidential when the OAuth session uses the following grants: Authorization Code Grant Client Credentials Grant Resource Owner Password Credentials Grant This client is capable of maintaining secure client authentications. When you select client type as Confidential, IBM webMethods Integration generates a client secret. This client secret will be required by IBM webMethods Integration when the client makes requests to the OAuth services. Public Select Public when the OAuth session uses the Implicit Grant type. This client is not capable of maintaining secure client authentications.
   Redirection URLs	Specify the URLs that IBM webMethods Integration will use to redirect the resource owner’s browser during the grant process. You can add more than one redirection URL by clicking the + icon. If you select the Authorization Code Grant or the Implicit Grant types, you must enter at least one Redirection URL for the client.
   Allowed Grants	Select the type of grant flow required by the client.
   Expiration Interval	Select the length of time (in seconds) that the access token is valid. Never Expires Indicates that the access token never expires. The Token Management page displays Lifetime for that token. Expires In Specify the number of seconds the access token is valid.
   Refresh Count	Select the number of times the access token can be refreshed. Unlimited Refresh the access token an unlimited number of times using the refresh token. The Token Management page displays Unlimited for that refresh token. Limited Specify the number of times to refresh the access token. The Token Management page will display the Refresh Count for that refresh token. If you specify 0 or leave the field empty, a refresh token will not be issued. Note Tokens can be refreshed only when using the Authorization Code Grant flow.

3. Click Add to add the client in the Client Registration page.
   
   

4. On the Client Registration page, if you want to associate scopes with a client, for a client, click the Associate OAuth Scopes icon. The Associated Scopes with ClientName(Version) page appears. The Associated Scopes with ClientName(Version) page displays the already associated scopes with the selected client.

   a. On the Associated Scopes with ClientName(Version) page, to associate existing scopes with the client, select Associate Existing Scopes.
   b. On the Select Scopes to Associate with ClientName(Version) dialog box, select the existing scopes to associate with the client and then select Associate.
   
   The newly associated scopes will appear in the Associated Scopes with ClientName(Version) page.
   c. To create a new scope and associate it with the selected client, select Associate New Scope. Create the new scope and select the services to add as Service URLs as described in the Managing Scopes section. The new scope will be associated with the selected client.
   d. To disassociate a scope from a client, select the scope on the Associated Scopes with ClientName(Version) page and then click Disassociate Selected Scopes.

Deleting or Deactivating Clients

When you delete a client, IBM webMethods Integration also deletes all the access tokens and refresh tokens for the client.
When you deactivate a client by moving the Status slider, all the access tokens and refresh tokens for the client become invalid. You can activate a deactivated client.

Managing Scopes

A scope defines the services the client can access on behalf of the resource owner. A scope consists of a name and one or more services. If access is granted for a scope, then access is granted for all the services in that scope. When a request is made, IBM webMethods Integration verifies that the scope is defined for a client. The client is allowed to access only the service URLs that are specified for the scope. If the requested scope is not defined, IBM webMethods Integration returns an error indicating that the scope is invalid.

Adding a Scope

1. From the IBM webMethods Integration navigation bar, click on the profile icon located at the top-right corner of the home screen and select Settings > OAuth 2.0 > Scope Management > Add New Scope.

   

2. On the Add New Scope dialog box, complete the following fields. Required fields are marked with an asterisk on the screen.

   

   Field	Description
   Name	Type a unique name for the scope. You cannot modify the scope name after a scope is saved. Scope names are not case-sensitive.
   Description	Type a description of the scope.
   Service URLs	This field appears once you have added the exposed Flow services and REST Resources. You can select both Flow services and REST Resources. A Service URL is a relative URL and it must start with /integration. For example, if the absolute URL is https://sub-domain.domain name/integration/rest/external/integration/run/development/projectID/flowservicename, then the Service URL is integration/rest/external/integration/run/development/fl1deb3b8565a30f0d557919/flow1. For REST APIs, if the absolute URL is /integration/restv2/development/projectID/RESTAPIName/ResourceName, then the Service URL is /integration/restv2/development/fl1deb3b8565a30f0d557919/customswagger/rad. Note If a REST API request URL has the following path variable: /abc/{pathvariable} and when you define the scope using this REST API, specify the value of the scope as /abc/*.
   Services	Click Add New Service to select the services that the client can access on behalf of the resource owner for executing the Flow services and REST Resources. Select the exposed Flow services and REST Resources that you want to add as Service URLs from the listed projects. The services dialog box displays the exposed Flow services and REST Resources available in all projects, that is, in custom projects and in the Default project. Note You can search by the project name, Flow Service name, or by the REST API name. The search function works for Flow services and REST APIs only after you have expanded the Flow services or REST API nodes in that project. It is recommended to first search for the project and then search for the Flow services and REST APIs in that project. In the services dialog box, select the exposed Flow services and REST APIs that you want to add as service URLs, and then click Add or Update to add or update the respective service URLs to that scope.

Generating Tokens

Clients use the access tokens to invoke REST URLs for running the flow services and REST APIs. You can generate tokens (Access Token and Refresh Token) by using a REST Client. IBM webMethods Integration supports the Authorization Code Grant, Implicit Grant, Client Credentials Grant, and Resource Owner Password Credentials Grant to generate the access tokens.

1. Open any REST client application, for example, Postman.

2. Generate Access token by entering the following details:

   Note

   • You can get the details from the client registration page. See, Registering Clients.
   • Configuring the same client application details across multiple custom OAuth-based accounts may lead to issues related to access token invalidation. To avoid the issues, configure a unique set of client application details for a custom OAuth-based account.
     

   Field	Description
   Callback URL	Specify the redirection URL added during client registration.
   Token Name	Provide a token name.
   Auth URL	Provide the Authorization Endpoint URL available on the Client page in the following format: https://abc.dev-int-aws-us.webmethods.io/integration/rest/oAuth/authorize
   Access Token URL	Provide the Access Token Endpoint URL available on the Client page in the following format: https://abc.dev-int-aws-us.webmethods.io/integration/rest/oAuth/getToken
   Client ID	Specify the client ID available on the Client page.
   Client Secret	Specify the client secret available on the Client page.
   Scope (Optional)	Specify the scope associated with the client.
   Grant Type	Select Authorization Code or Implicit.

3. Login to IBM webMethods Integration with your credentials. The permissions page appears.

4. Select the scopes that you want to grant access and click Grant Access.

   

   An access token is generated. A refresh token may also be generated depending on the Refresh Count configured for your client, and also if your grant type is Authorization Code Grant.

Refreshing Access Tokens

You can refresh Access Tokens using Refresh Tokens.

1. Open any REST Client application.

2. Make a HTTP POST call with the following details:

   Field	Description
   Post URL	Provide the following URL: https://abc.dev-int-aws-us.webmethods.io/integration/rest/oAuth/getToken
   Query Parameters	Provide the following query parameters: grant_type - The Grant Type value will be refresh_token. refresh_token - This is the refresh token obtained while generating the tokens. Example of an HTTP POST request for refreshing an access token: https://abc.dev-int-aws-us.webmethods.io/integration/rest/oAuth/getToken?grant_type=refresh_token&refresh_token= refresh_token_id Note Select Basic Auth as the Authorization type and specify Client ID and Client Secret as the Username and Password while refreshing the token. Use content-type as application/x-www-form-urlencoded only while calling OAuth getToken API. The OAuth getToken API call should not have any body, it should only have Query Parameters.

   An access token is generated that can be used to invoke the service URLs. The Refresh Count value decreases by 1.

Deleting Tokens

You can use this page to delete the active tokens issued by IBM webMethods Integration. Client applications use these tokens to access the resources on IBM webMethods Integration. When you delete the tokens, the client application can no longer access the resources owned by the resource owners.

See the Generating Tokens section on how to generate tokens (Access Token and Refresh Token) by using a REST Client.

For expired Access Tokens, the Expiry Time column on the Token Management page displays Expired. If the Refresh Count is also 0, then the row in the Token Management page is removed.

1. From the IBM webMethods Integration navigation bar, click on the profile icon located at the top-right corner of the home screen and select Settings > OAuth 2.0 > Token Management.

2. For a token, click the Delete icon. When you delete a token from the list of active tokens, IBM webMethods Integration deletes both the access token and the refresh token. If you want to prevent a client from accessing resources, you can delete the client.

Running Services Using OAuth 2.0

1. Open any REST Client application.

2. Type the Request URL and change the HTTP method to POST.

   

3. Run the Flow services or REST API endpoint using the access token genarated.