OAuth 2.0

Protect integration services and REST APIs using the OAuth 2.0 protocol.

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.

Note: webMethods.io Integration acts both as a Resource server and as an Authorization server.

Configuring OAuth 2.0

webMethods.io 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.

Steps Description
Define Clients Define the clients that are authorized to invoke services in webMethods.io Integration. Specify the client name, version number of the client, client type, redirection URLs, allowed grants, expiration interval, and the refresh count. See Registering Clients for more information.
Define 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.
Associate scopes to a client Associate defined scopes with the registered clients. When you associate scopes, you authorize the scopes that each client can access.
Generate Tokens Generate tokens (Access Token and Refresh Token) by using a REST Client. See Generating Tokens for more information.
webMethods.io Integration supports the Authorization Code Grant, Implicit Grant, Client Credentials Grant, and the Resource Owner Password Credentials Grant to generate the access tokens. Clients use the tokens to execute REST URLs for running the integrations. After you generate the tokens, the tokens are available in the Token Management page in webMethods.io Integration.

Registering Clients

Before a client can request access to a protected resource, it should register with webMethods.io 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 webMethods.io Integration.

Adding Clients

  1. From the webMethods.io 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 webMethods.io 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, webMethods.io Integration generates a client secret. This client secret will be required by webMethods.io 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 webMethods.io 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, webMethods.io 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.

Note: If you are running a Flow service or REST API multiple times, for example if you have scheduled the Flow service or REST API, and if you deactivate or delete the client while the scheduled Flow service or REST APIs are executing, the Flow service or REST API executions will still continue to work sometimes for a maximum of 840 seconds. After 840 seconds, the session expires and the access token validation happens again. This is applicable only if the access token has not expired.

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, webMethods.io 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, webMethods.io Integration returns an error indicating that the scope is invalid.

Note: You cannot delete a scope that is used by a client. Also, a scope cannot be deleted if it is associated with an existing token. Users who have the required permission can create, edit, and delete scopes.

Adding a Scope

  1. From the webMethods.io 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

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

  1. Open any REST client application.

  2. Generate Access token by entering the following details:

    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 webMethods.io 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.

Adding Tokens

Note: This option is available for Develop Anywhere, Deploy Anywhere enabled tenants only.

  1. Go to User Profile > Settings > OAuth 2.0 > Token Management. All available tokens are listed.

  2. Click Add New Token. The Add New Token dialog box appears.

  3. Select the client for which the token must be generated from the Client drop-down list.

  4. Specify the number of days for which the token is valid from the Expiry Time drop-down list. The default value is 30 days.

  5. Click Generate Token. The token is generated and listed.

  6. Copy the access token and save it in your local system for future reference.

  7. Click Close to exit the Add New Token dialog box. The Token Management page appears and the newly added access token is listed in the Tokens table.

Notes:

  • You can add multiple tokens to a single Edge Runtime.

  • You must not delete any of the OAuth tokens associated with an Edge Runtime. Otherwise, you will not be able to run the services or workflows using that Edge Runtime. If you delete the OAuth token, then the error message appears stating that the Edge Runtime is unavailable.

Deleting Tokens

You can use this page to delete the active tokens issued by webMethods.io Integration. Client applications use these tokens to access the resources on webMethods.io 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.

Note: Only users who have the required permission can delete tokens.

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 webMethods.io 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, webMethods.io 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.

Note: If you are running a Flow service or REST API multiple times, for example if you have scheduled the Flow service or REST API, and if you delete the access token or deactivate or delete the client while the scheduled Flow service or REST APIs are executing, the Flow service or REST API executions will still continue to work sometimes for a maximum of 840 seconds. After 840 seconds, the session expires and the token validation happens again. This is applicable only if the token has not expired.

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.