Configuring OAuth

What Is OAuth?

The OAuth 2.0 Authorization Framework (OAuth) 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, laptop, etc). 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.

An overview of the differnt roles in OAuth

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

Using OAuth with Integration Server

Integration Server can be an OAuth client, an authorization server, or a resource server. Integration Server Administrator provides an OAuth configuration feature that developers can use to create and manage these roles. To enable the OAuth features, your Integration Server must be equipped with a license from Software AG. For information about licensing, see Important Considerations for Using OAuth Features.

Integration Server as an OAuth Client

When Integration Server is an OAuth client application, you use the pub.client.oauth:executeRequest service to access resources from providers such as Facebook, Google, Twitter, or Integration Server. For information about accessing resources using the pub.client.outh:executeRequest service, see webMethods Integration Server Built-In Services Reference .

Integration Server as an Authorization Server

When Integration Server acts as an authorization server, it receives authorization requests from client applications. Client applications initiate the request by invoking the pub.oauth:authorize service. The authorization server handles the interactions between the client application, resource server, and resource owner for approval of the request. For information about configuring Integration Server as an authorization server, see Configuring Integration Server for OAuth.

When Integration Server acts as an authorization server, it issues access tokens as bearer tokens. A bearer token is an access token that allows any party in possession of the access token (Bearer) to use the token. The authorization server retains the information about the bearer tokens it issues, including the user information. When the client presents a bearer token to the resource server, the resource server sends the token to the authorization server to ensure that the token is valid and that the requested service is within the scope for which the access token was issued. A scope is the definition of the folders and services (resources) that the client can access on behalf of a resource owner.

If the user is authorized to access the folders and services, the resource server executes the request. If the user does not have privileges to access the resources, the resource server rejects the request. For information about user privileges, see Managing Users and Groups.

Integration Server as an External Authorization Server

Access tokens generated by Integration Server’s authorization server can be used to access resources in other vendors' servers. That is, an Integration Server authorization server can respond to a requests for access token introspection from a resource server that is not an Integration Server. This is part of Integration Server support for RFC 7662, OAuth 2.0 Token Introspection.

The pub.oauth* services provide clients with services for interacting with an Integration Server used as an OAuth 2.0 authorization server, including services for requesting a token, determining whether a token is still active, refreshing an access token, and revoking an access token. The introspection endpoint for the Integration Server authorization server is the following URL:

https://host:port/invoke/pub.oauth/introspectToken

This invokes the pub.oauth:introspectToken service on the Integration Server authorization server located at host:ports.

For more information about built-in services for OAuth see, OAuth Folder .

Integration Server as a Resource Server

When Integration Server acts as a resource server, it receives requests from client applications that include an access token. The resource server asks the authorization server to validate the access token and user. If the token is valid and the user has privileges to access the folders and services, the resource server executes the request. The resource server and the authorization server might be the same Integration Server instance or might be different Integration Server instances. The authorization server might also be a third-party authorization server. For information about using Integration Server as a resource server, see About Using Integration Server as the Resource Server. For information about configuring an third-party authorization server, see Using an External Authorization Server.

OAuth Client Types

OAuth 2.0 Authorization Framework defines two types of clients.

  • A confidential client is a client that supplies a client ID and client secret to the authorization server in order to obtain an access token. Confidential clients correspond to an account on the authorization server. If a client does not have the proper credentials (client ID and secret) for the user account, the authorization server does not grant the client an access token.

    To specify a confidential client in Integration Server Administrator, set Type to Confidential. For more information, see Registering Clients.

  • A public client is a client that uses only a client ID for identification, with no other credentials. Public clients are typically implemented in a browser using a scripting language such as JavaScript. Because the authorization server does not require any other credentials, the authorization server grants any client with a valid client ID an access token.

    To specify a public (implicit) client in Integration Server Administrator, set Type to Public. For more information, see Registering Clients.

Authorization Grant Types Supported by Integration Server

The flow of authorization requests and responses between the resource owner, client application, authorization server, and resource server depends on the authorization grant type defined by the OAuth session. Integration Server supports the following authorization grant types:

  • Authorization code grant
  • Implicit grant
  • Resource owner password credentials grant
  • Client credentials grant

For each OAuth client registered with an Integration Server, you must specify the OAuth grant types that a client can use.

Authorization Code Grant

The authorization code grant type is used to authenticate and provide access to clients that have credentials on the authorization server. This grant type requires the client to authenticate to the authorization server before obtaining an access token.

You use the authorization code grant type to authenticate and provide access to confidential and public clients.

When using the authorization code grant type, the authorization server can issue a refresh token to the client application along with the access token. A refresh token enables clients to get a new access token without requesting additional approval from the resource owner. When the access token expires, the client application can use the pub.oauth:getToken service to pass the refresh token to the authorization server to request a new access token.

The following diagram illustrates how the Integration Server authorization server participates in the authorization code grant process.

Figure 1. Authorization Code Grant Flow
Activity flow for authorization code grant type

The following table describes each step in the authorization code grant flow.

Stage Description
1 The client application initiates the process by calling the pub.oauth:authorize service to request access to the resource owner’s data.
If PKCE is required for public clients, the client must create a code_verifier value. The client must pass the following additional values to the pub.oauth:authorize service:
  • code_challenge, which is a transformation of the code_verifier value.
  • code_challenge_method, which is the transformation method for the code_verifier.
For more information about PKCE, see Using PKCE with the Authorization Code Grant.
2 The pub.oauth:authorize service validates the request. If valid, the service responds with an HTML page that informs the resource owner that the client application is requesting access within a specified scope. The resource owner uses the HTML page to approve or deny the request.

Integration Server saves the supplied code_challenge and code_challenge_method values in the OAuthPKCE cache.
3 When the resource owner approves the request, the approval page invokes an internal service on Integration Server. If the resource owner denies the request, an error is returned.
4 Integration Server generates an authorization code for the client application. The server uses HTTP redirection to instruct the resource owner's browser to transmit the authorization code to the redirection URI provided by the client application.
5 The service at the client application’s redirection URI passes the authorization code to the pub.oauth:getToken service on Integration Server to exchange the authorization code for an access token. Integration Server also ensures that the client is allowed to use the authorization code grant.

If PKCE is in use, the client must also supply the code_verifier value to pub.oauth:getToken.
6 Integration Server issues an access token to the client application. If set to do so, the authorization server also issues a refresh token to the client.

If PKCE is in use, Integration Server applies the code_challenge_method to the supplied code_verifier. If it matches the code_challenge provided in Stage 1, Integration Server issues an access token.
7 The client application uses the access token to request a resource on the resource server.
8 The resource server checks with authorization server to make sure the access token is valid. If it is, the resource server checks that the requested service is within the scope for which the access token was issued. It also checks that the resource owner is authorized to access the requested resource.

Using PKCE with the Authorization Code Grant

Proof Key for Code Exchange (PKCE) is an OAuth standard that mitigates the authorization code interception attack. Public OAuth clients that use the authorization code grant are vulnerable to this attack and should use PKCE to protect themselves.

The PKCE standard is defined at https://datatracker.ietf.org/doc/html/rfc7636. The PKCE standard describes how the client should generate the additional inputs passed to these endpoints.

PKCE is required for public clients when the global setting Require PKCE is set to yes and the client uses the authorization code grant type.

When PKCE is required for public OAuth clients and Integration Server is the authorization server, public OAuth clients must create a secret called the code_verifier value and transform it. The client must supply the transformed version (code_challenge) and, optionally, the transformation method (code_challenge_method) to the pub.oauth:authorize service.

The values for code_challenge_method are S256 and plain. When code_challenge_method is S256, code_challenge is base64-encoded, SHA-256 hash of the code_verifier value. The default value is plain. When code_challenge_method is plain, the code_challenge value is the same as the code_verifier.

Note: You can use the com.softwareag.util.PKCE.createCodeVerifier() method to transform a code_verifier value into a base64-encoded, SHA-256 hash to use as the value for code_challenge.

If PKCE is in use, when the client invokes the token endpoint service pub.oauth:getToken on Integration Server to exchange the authorization code for an access token, the client must supply the additional input parameter code_verifier. Integration Server applies the code_challenge_method to transform the supplied code_verifier value. If the transformed value matches the code_challenge sent to the authorization endpoint, the token endpoint returns an access token.

Note: The code_verifier input parameter is required when a code_challenge has been sent to the authorization endpoint (pub.oauth:authorize) and the grant_type is authorization_code. This requirement applies to public clients that supplied a code_challenge value to pub.oauth:authorize. Once a public client supplies code_challenge to the authorization endpoint, PKCE processing is triggered for the remainder of the authorization grant code process. Whether or not Require PKCE is selected for the Integration Server acting as an authorization server is irrelevant.

Integration Server provides a Java class to assist clients with PKCE. The com.softwareag.util.PKCE class includes the createCodeVerifier method for creating a code_verifier and the createCodeChallenge method for transforming a code_verifier value into a base64-encoded, SHA-256 hash to use as the value for code_challenge. The class also includes the pkceMatch method for determining if the code_verifier value matches the code_challenge value. For more information, see the webMethods Integration Server Java API Reference .

Implicit Grant

The implicit grant type is used to authenticate browser-based applications and mobile applications. This grant type is less secure than the authorization code grant because it does not require the client to authenticate with the authorization server. In addition, the implicit grant type passes the access token through the resource owner's browser, exposing it to theft by malicious applications on the resource owner's device. The following diagram illustrates how the Integration Server authorization server participates in the implicit grant process.

You use the implicit grant type to authenticate and provide access to public clients.

Figure 2. Implicit Grant Flow
Activity flow for impliicit grant type

The following table describes each step in the implicit grant flow.

Stage Description
1 The client application initiates the process by calling the pub.oauth:authorize service to request access to the resource owner’s data.
2 The pub.oauth:authorize service validates the request. If valid, the service responds with an HTML page that informs the owner that the client application is requesting access within a specified scope. The resource owner uses a form on the HTML page to approve or deny the request.
3 When the resource owner approves the request, the approval page invokes an internal service on Integration Server. If the resource owner denies the request, an error is returned.
4 Integration Server redirects the resource owner's browser to the client application's redirection endpoint, appending the access token as a fragment on the redirection URI.
5 The resource owner’s browser holds the access token in memory until the client application retrieves the access token.
6 The client application uses the access token to request a resource on the resource server.
7 The resource server checks with authorization server to make sure the access token is valid. If it is, the resource server makes sure that the requested service is within the scope for which the access token was issued. It also checks that the resource owner is authorized to access the requested resource.

Resource Owner Password Credentials Grant

The resource owner password credentials (ROPC) grant allows resource owners to provide trusted clients with their credentials which the clients can then use to obtain an access token. Clients can use the access token to access resources on the resource server. The intent of the ROPC grant is to provide access to resources in situations where there is an existing trust relationship between the resource owner and the client or when it is not possible to use other authorization grant types.

With the ROPC grant type, the client does not need resource owner approval nor does the client need a redirection endpoint. Instead the client calls the token endpoint on the authorization server directly, presenting the resource owner’s credentials for authentication. The token endpoint authenticates the credentials and issues an access token.

When using the ROPC grant type, the authorization server can issue a refresh token to the client application along with the access token. A refresh token enables clients to get a new access token without requesting additional approval from the resource owner. When the access token expires, the client application can use the pub.oauth:getToken service to pass the refresh token to the authorization server to request a new access token.

You use the ROPC grant type to authenticate and provide access to confidential clients and public clients.

The ROPC grant type is the least secure of all the grant type supported by Integration Server.

Figure 3. Resource Owner Password Credentials Grant Flow
Activity flow for resource owner password credentials grant

The following table describes each steep in the ROPC grant flow.

Stage Description
1 The resource owner provides their credentials to the client application
2 The client application presents the resource owner’s credentials to the token endpoint, the pub.oauth:getToken service, on the authorization server.
3 On the authorization server, the pub.oauth:getToken service authenticates the provided credentials and verifies that the credentials belong to a confidential client allowed to use the resource owner password credentials (ROPC) grant. The service also checks that the scopes specified with the client request are allowed for the client. The authorization sever returns an access token to the client. If set to do so, the authorization server also returns a refresh token to the client.
4 The client application uses the access token to request a resource on the resource server.
5 The resource server checks with authorization server to make sure the access token is valid. If it is, the resource server makes sure that the requested service is within the scope for which the access token was issued. It also checks that the resource owner is authorized to access the requested resource.

Client Credentials Grant

The client credentials grant is used to authenticate and provide access to clients that have credentials on the authorization server. The client credentials grant allows the client to use their credentials to obtain an access token that can the be used to access resources. The client credentials grant is often used to access resources that are already under the control of the client, or when the resource owner trusts the client to access its resources, or for machine-to-machine interactions. An example of machine-to-machine interaction might be a background process that runs on the resource owner’s device and the background process needs access to resources protected by OAuth.

Unlike the authorization code grant type, a client using the client credentials grant does not need resource owner approval before obtaining an access token, nor does the client need a redirection endpoint. Instead, the client presents credentials directly to the token endpoint and requests an access token. The token endpoint authenticates the credentials and issues an access token. The token endpoint does not issue a refresh token as refresh tokens are not supported by the client credentials grant.

The client credentials grant type is less secure than the authorization code grant type.

A client that uses the client credentials grant must have credentials on the authorization server which means the client must be a confidential client. When you create a client that will use the client credentials grant, you must give the client permission to access the resources it needs. This is different than the other grant types where Integration Server knows the resource owner because the resource owner either provided its credentials when approving the request (authorization code and implicit grants) or the client supplies the resource owner’s credentials (ROPC grant) With the client credentials grant, Integration Server does not know the owner because the client does not need resource owner approval. Consequently, it is the client who must have permission to access the resources. You must add the client to one or more user groups that have the access permissions that the client needs.

Figure 4. Client Credentials Grant Flow
Activity flow for client credentials grant type

The following table describes each step in the client credentials grant flow.

Stage Description
1 The client application initiates the process by presenting its credentials to the token endpoint, the pub.oauth:getToken service, on the authorization server.
2 On the authorization server, the pub.oauth:getToken service authenticates the client and verifies that the credentials belong to a confidential client allowed to use the client credentials grant. The service also checks that the scopes specified with the client request are allowed for the client. The authorization sever returns an access token to the client.
Note: A refresh token is not returned for a client credentials grant.
3 The client application uses the access token to request a resource o the resource server.
4 The resource server checks with authorization server to make sure the access token is valid. If it is, the resource server checks that the requested resource is within the scope for which the access token was issued.

The Integration Server OAuth Services

Integration Server provides public services for use with OAuth in the WmPublic package.

The following table lists services that you use to authorize a client application to access a resource server.

Service Description
pub.oauth:authorize Initiates an authorization request from the client application to the Integration Server authorization server.
pub.oauth:getAccessToken

Requests an access token from the Integration Server authorization server. The request includes the authorization code sent to the redirection URI by the authorization server.

The authorization server validates the request and generates an access token and refresh token (optional). The tokens, along with the client identifier, expiration time, and scope are stored in the authorization server's cache.

Note: The pub.oauth:getAccessToken service is deprecated. Use pub.oauth:getToken instead.
pub.oauth:getToken

Requests an access token from the Integration Server authorization server. The request includes the authorization code sent to the redirection URI by the authorization server.

The authorization server validates the request and generates an access token and refresh token (optional). The tokens, along with the client identifier, expiration time, and scope are stored in the authorization server's cache.

Note: The pub.oauth:getToken service replaces thepub.oauth:getAccessToken and pub.oauth:refreshAccessTokenservices which are deprecated.
pub.oauth:introspectToken Checks whether an access token or refresh token generated by an Integration Server used as an authorization server is active.
pub.oauth:refreshAccessToken Sends a request to the Integration Server authorization server to refresh the access token.
Note: The pub.oauth:refreshAccessToken service is deprecated. Use pub.oauth:getToken instead.

                           pub.oauth:removeExpiredAccessTokens
                        
 Removes expired access tokens from the database.
pub.oauth:revokeToken Revokes a token on an Integration Server authorization server.

For more information about using the Integration Server OAuth services, see OAuth Folder .

Important Considerations for Using OAuth Features

Keep the following points in mind when using OAuth features:

  • If you are using webMethods Enterprise Gateway to process requests from external clients, keep in mind that OAuth configuration settings in Integration Server Administrator (Security > OAuth) are only available on Integration Servers that do not act as an Enterprise Gateway Server. The Internal Server that sits behind the firewall processes all OAuth requests. For more information about webMethods Enterprise Gateway, see Configuring webMethods Enterprise Gateway.

    Some companies use Enterprise Gateway Server inside their firewall, where it is safe to set up a database and perform OAuth configuration. To allow access to OAuth configuration from Integration Server Administrator, even when an Enterprise Gateway port is enabled, set the server configuration parameter watt.server.oauth.alwaysAvailable to true. The watt.server.oauth.alwaysAvailable parameter should be set to true only when Integration Server is inside the corporate firewall. This is because OAuth requires a database, which should not be placed outside the firewall.

    Note: The watt.server.oauth.alwaysAvailable parameter is available after applying a fix that includes PIE-80891 (IS_10.11_Core_Fix9).
  • In order for Integration Server to log OAuth activity, the Security logger must be enabled and configured to log the following security areas: Authentication and Authorization. For detailed instructions on enabling the security logger and selecting security areas to audit, see the webMethods Audit Logging Guide .
  • For OAuth authorization failures to appear in the error log, the watt.server.oauth.log.authErrors server configuration parameter must be set to true. By default, this parameter is set to false, meaning Integration Server does not write OAuth authorization errors to any log.

Configuring Integration Server for OAuth

Before you can begin to use OAuth in your Integration Server environment, you need to specify settings for the authorization server and/or resource server, depending on which role the Integration Server plays in you OAuth solution. When the authorization server and resource server are configured, you can start registering clients and managing your OAuth scopes.

The following table describes the basic stages for configuring Integration Server for OAuth.

Stage 1 Configure OAuth settings.

During this stage, you configure the OAuth settings on Integration Server. Integration Server is configured to use certain OAuth settings by default. For information about configuring these settings to reflect those for your system, see Configuring OAuth Settings.

Note: This stage primarily applies to an Integration Server being used as an authorization server. However, if the Integration Server is acting as the resource server, you must use the Authorization server field on the Security> OAuth > Edit OAuth Global Settings page to identify the authorization server for the resource server.
Stage 2 Define clients.

During this stage, you define the clients that are authorized to access the authorization server and specify which grant types they can use. For information about registering, modifying, and deleting clients, see Defining Clients.

When using Integration Server as the authorization server, the Integration Server and the resource server need to have the same resource owners. This requirement does not apply when using an external authorization server or if all of your clients will use the client credentials grant type.

If you are using Integration Servers for the authorization and resource servers, you can define the client_id values on one Integration Server and then deploy the values to the other Integration Server.

For clients that use the client credentials grant, the user accounts associated with the clients need to be on the authorization server and the resource server.
Stage 3 Define scopes.

During this stage, you define the scopes available for the clients to access. For information about adding, modifying, and deleting scopes, see Defining Scopes.

Your authorization server and resource server must have the same scope names. You can define the scope names on each server. Or, if you are using Integration Servers for the authorization and resource servers, you can define the scopes on one Integration Server and then deploy the values to the other Integration Server.
Stage 4 Associate scopes to clients and vice versa.

During this stage, you associate scopes to clients. When you associate scopes and clients, you authorize the scopes that each client can access. For information about adding, removing, and viewing the associations between scopes and clients, see Associating Scopes and Clients.

Note: This stage applies to an Integration Server being used as an authorization server only. You do not need to complete this stage for an Integration Server being used as a resource server.
Stage 5 If you want to prevent specific client applications from accessing resources after the authorization server has granted an access token, you can do either of the following:
  • On the authorization server, delete the active access and refresh tokens granted for that client application. For information about viewing and deleting tokens, see Managing Tokens.
  • On the resource server, disable the client application. For information about disabling client applications, see Enabling and Disabling Clients.

Configuring OAuth Settings

About this task

The OAuth global settings for the authorization server control whether HTTPS is required for OAuth communications. You can also specify global values for authorization code and access token expiration intervals. The expiration intervals can be set globally or configured for each individual client.

To configure the OAuth settings

Procedure

  1. Open Integration Server Administrator if it is not already open.
  2. Go to Security > OAuth.
  3. Click Edit OAuth Global Settings.
  4. Under Authorization Server Settings, complete the following fields for when Integration Server acts as the authorization sever.
    Field Description
    Require HTTPS Indicates whether the authorization server should require an HTTPS connection to authorize requests.

    If enabled (the default), Integration Server requires that the authorization server uses HTTPS to invoke the pub.oauth services. If disabled, Integration Server allows client applications to use HTTP to access the pub.oauth services.

    If Require HTTPS is enabled and the client application accesses any of the pub.oauth services over HTTP, Integration Server issues an HTTP 400 error response to the client and writes a service exception to the error log.

    Important: You can disable Require HTTPS to simplify development, but you should use HTTPS in production in accordance with the OAuth Framework. If you do not require HTTPS, the authorization server transmits access tokens in clear text, making them vulnerable to theft.
    Require PKCE Indicates whether PKCE (Proof Key for Code Exchange) is required for all public OAuth clients using the authorization code grant.

    Select the Require PKCE check box to require all public OAuth clients to supply a code_challenge and code_challenge_method to the authorization endpoint (pub.oauth:authorize) service and a code_verifier to the token endpoint (pub.oauth:getToken service).

    Clear the Require PCKE check box to indicate that public OAuth clients are not required to supply the additional inputs. However, any clients that do send a code_challenge and code_challenge_method to the authorization endpoint will be using the PKCE feature to mitigate the authorization code interception attack. A subsequent request by the client to the token endpoint must include the code_verifier input parameter.
    Authorization code expiration interval Specifies the length of time (in seconds) that the authorization code issued by the authorization server is valid.

    Valid values are between 1 and 2147483647. The default value is 600.
    Access token expiration interval Specifies the length of time (in seconds) that access tokens issued by the authorization server are valid.
      Select To.
      Never Expires Indicate that the access token never expires
      Expires in and enter the number of seconds. The maximum value is 2147483647. The default is 3600. Specify the length of time that the access token is valid
    Token endpoint authorization Specifies whether the token endpoint accepts an existing session or requires credentials for authentication. The pub.oauth:getToken service functions as the token endpoint. Clients invoke this service to requests an access token from the Integration Server authorization server.
      Select To
      Accept existing session Indicate that the token endpoint service will accept requests from clients that have an active session on Integration Server. If these clients supply a valid session identified in the Cookie request header, the clients do not have to provide credentials to use the pub.oauth:getToken service. This is the default behavior and matches the behavior that existed prior to the Integration Server version 10.3.
      Require credentials Require clients to provide their credentials in the Authorization request header every time they request a new access token or refresh an existing access token by calling the pub.oauth:getToken service.
     
    Note: The pub.oauth:getToken service replaces the pub.oauth:getAccessToken and pub.oauth:refreshAccessToken services which are deprecated.
    Note: Token endpoint authorization impacts clients using the authorization code grant type, resource owner password credentials grant type, and client credentials grant type.
  5. Under Resource Server Settings, if you are configuring Integration Server as a resource server, in the Authorization server list, select the server that will be the authorization server.

    You can use an Integration Server as the authorization server or you can use an external authorization server. The Authorization server list displays the configured remote server aliases and external authorization server aliases that are available for use.

    If you intend to use a remote Integration Server as the authorization server and you have not already defined an alias for the authorization server, click the Authorization server link to go to the External servers > Remote servers page. For information about creating a remote server alias, see Setting Up Aliases for Remote Integration Servers.

    If you intend to use an external authorization server and you have not already defined an alias for the authorization server, click the Add External Authorization Server link to go to the External Authorization Server > Add page. For information about creating an alias for an external authorization server, see Using an External Authorization Server.

    If you are configuring Integration Server as the authorization server only, Integration Server ignores the value of the Authorization server field.

  6. Click Save Changes.

Defining Clients

About this task

Before a client application (client) can request access to a protected resource, you must use the Integration Server Administrator to register the client with the authorization server.

Registering Clients

About this task

Clients must be registered with the Integration Server acting as the authorization server to be able to access resources protected by OAuth. 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 token expiration and refresh information.

For each OAuth client registered with Integration Server, you must specify the OAuth grant types that the client can use to access the server. Keep the following information in mind when selecting the grant types that a client can use.

  • Only confidential clients may use the client credentials grant and resource owner password credentials grants. You cannot select either of these grant types for public clients. If a client requests an access token using a grant that it is not allowed to use, Integration Server will reject the request and return an unauthorized_client OAuth error.
  • When you register a new client, Integration Server automatically selects the Authorization Code Grant check box.
  • The authorization code grant is the most secure of the four OAuth grant types. supported by Integration Server.
  • If you select the Authorization Code Grant or the Implicit Grant check boxes, you need to enter at least one Redirection URI for the client.
  • After registering a client that will use the client credentials grant, you must give the client permission to access the resources it needs. This is different than the other grants. For the other grants, Integration Server knows the owner because the resource owner is involved in the grant flow. Specifically, when an access token is being used to access a resource, Integration Server checks that the owner has permission to access the resource. With the client credentials grant, Integration Server does not know the owner. Consequently, it is the client who must have permission to access the resources. After registering the client, you must add the client to one or more user groups that belong to the access control lists (ACLs) that the client needs. The client ID generated for the client by Integration Server appears as the user name on the Security > User management pages.
Note: Prior to Integration Server version 10.3, registering a client did not require specifying allowed grant types. Rather, all registered clients were allowed to use the authorization code grant type and the implicit grant type. Beginning in Integration Server 10.3, all new clients must specify at least one grant type. Clients migrated to Integration Server 10.3 will still be able to use the authorization code grant type and the implicit grant types.

Complete the following steps to register a client with the authorization server.

To register a client

Procedure
  1. Open Integration Server Administrator of the Integration Server defined as the authorization server if it is not already open.
  2. Go to Security > OAuth.
  3. Click Client Registration.
  4. Click Register Client.
  5. Under Client Configuration, complete the fields as follows:
    Field Description
    Name Specifies the name of the client.

    The name cannot contain the following characters:

    & ( ) \ ; , / " : ' < >

    Note: You cannot create clients with the same Name and Version combination.
    Version Specifies the version number of the client.

    The version cannot contain the following characters:

    & ( ) \ ; , / " : ' < >

    Note: You cannot create clients with the same Name and Version combination.
    Type Specifies the type of the client according to its ability to communicate with the authorization server.
    Specify... When...
    Confidential The client is capable of maintaining secure client authentications. When you select client type as Confidential, Integration Server generates a client secret. This client secret will be required by Integration Server when the client makes requests to the OAuth services. Specify Confidential when the OAuth session uses the authorization code grant type, resource owner password credentials grant type, or the client credentials grant type.
    Public The client is not capable of maintaining secure client authentications. Specify Public when the OAuth session uses the implicit grant type. For more information, see Implicit Grant.
    Description Optional. Specifies a description of the client.
    Redirect URIs Specifies the URIs that the authorization server will use to redirect the resource owner's browser during the grant process.

    You can add more than one URI at a time by specifying multiple lines, one URI to a line. Press the Enter key to separate lines.

    If you select the Authorization Code Grant or the Implicit Grant types, you need to enter at least one Redirection URI for the client.
    Allowed Grants Specifies the OAuth grant types that the client can use to with Integration Server. Select one or more of the following:
    • Authorization Code Grant
    • Implicit Grant
    • Client Credentials Grant
    • Resource Owner Password Credentials Grant

    The default is Authorization Code Grant which is the most secure grant type.

    If you select Authorization Code Grant or Implicit Grant, you need to enter at least one redirect URI for the client.

    Only confidential clients may use the client credentials and resource owner password credentials grants. You cannot select either of these grants for public clients. If a client requests an access token using a grant that it is not allowed to use, Integration Server will reject the request and return an unauthorized_client OAuth error.
  6. Under Token, specify the following information about the tokens issue to the client:
    Field Description
    Expiration Interval Specifies the length of time (in seconds) that the access token is valid.
      Select... To...
      Use OAuth Global Setting Use the setting specified in the Access token expiration interval field on the OAuth page. This setting is shown in angle brackets. For more information about the Access token expiration interval field, see Configuring OAuth Settings.
      Never Expires Indicate that the access token never expires.
      Expires in Specify a specific time interval. Enter the number of seconds that the access token is valid in the field provided. The maximum value is 2147483647. The default is 3600.
    Refresh Count Specifies the number of times the access token can be refreshed.
    Note: Tokens can only be refreshed when using the authorization code grant flow and the resource owner password credentials (ROPC) grant flow.
      Select... To...
      Unlimited Refresh the access token an unlimited number of times.
      Limit Specify the number of times Integration Server can refresh the access token.

    If you specify any value greater than 0, Integration Server will issue a refresh token to enable the access token to be refreshed the specified number of times. When the access token expires, the client can use the pub.oauth:getToken service to submit a token refresh request to the authorization server.

    If you specify 0 or leave the Limit field empty, Integration Server does not issue a refresh token.

    The maximum value is 2147483647. The default is 0.
  7. Click Save Changes.

    Integration Server generates a client ID. If you specified Confidential in the Type field, Integration Server also generates a client secret. Integration Server requires the client ID, client secret, or both when the client invokes the OAuth services.

What to do next
Notes:
  • When a confidential client is registered, a corresponding Integration Server user account is created. The user name is the client ID and the password is the client secret. If an existing client is changed from confidential to public or vice versa, the corresponding user account is created or deleted.
  • The password automatically generated for the Integration Server user account might not conform to password restrictions. However passwords that Integration Server generates automatically for OAuth clients are secure 36 character pseudo-random values.
  • When a confidential OAuth client is created on a clustered Integration Server, the client's user account is saved to the local file system but not to the other servers in the cluster. When the client sends a request to the OAuth token endpoint on another server in the cluster, a user account is dynamically created for the client on the other server.

Enabling and Disabling Clients

About this task

If you want to temporarily disable access to resources for all the access tokens issued to a registered client, you can disable that client. When you disable a client, the introspection endpoint (pub.oauth:introspectToken) returns "active=false" for all tokens issued to the client. This causes the resource server to deny access to requests that use one of the disabled client's tokens.

Note: The watt.server.oauth.disableClient.disableTokens server configuration parameter controls whether or not the OAuth introspection endpoint, the pub.oauth:introspectToken service, considers whether a client account is disabled or enabled when determining if an access token is active. When watt.server.oauth.disableClient.disableTokens is set to true, the pub.oauth:introspectToken service considers the token to be inactive if the client account to which the token was issued is disabled. When set to false, the pub.oauth:introspectToken service does not consider the enabled/disabled state of the client account to which the access token was issued when evaluating an access token. For more information about watt.server.oauth.disableClient.disableTokens, see watt.server.

Complete the following steps to enable or disable a registered client.

To enable or disable a client

Procedure
  1. Open the Integration Server Administrator if it is not already open.
  2. Go to Security > OAuth.
  3. Click Client Registration.
  4. Under the Active column of the Registered Clients list, select one of the following:
    Click To
    No Enable a client.
    Yes Disable a client.
  5. When prompted to confirm that you want to enable or disable the registered client, click OK.

Editing Clients

About this task

Complete the following steps to edit a registered client.

To edit a client

Procedure
  1. Open the Integration Server Administrator if it is not already open.
  2. Go to Security > OAuth.
  3. Click Client Registration.
  4. Under Registered Clients, click the Application Name or Client ID for the client that you want to edit.
  5. Update the information for the client.
    Note: You cannot edit the data displayed in the ID or Secret fields. Integration Server Administrator masks the contents of the Secret field. Click Reveal Secret to show the secret. Click Hide Secret to mask the secret again.
  6. Click Save Changes.

Deleting Clients

About this task

Complete the following steps to delete a registered client.

Important: When you delete a client, Integration Server also deletes all the access and refresh tokens for the client.

To delete a client

Procedure
  1. Open the Integration Server Administrator if it is not already open.
  2. Go to Security > OAuth.
  3. Click Client Registration.
  4. Locate the client in the Registered Clients list, and click the Delete icon icon in the Delete column.
  5. When prompted to confirm that you want to delete the registered client, click OK.

Defining Scopes

About this task

A scope indicates the resources the client can access on behalf of a resource owner. A scope consists of a name and one or more Integration Server folders, services, or both. If access is granted for a scope, then access is granted for all folders and services in that scope. You map the scope to a registered client to indicate the namespace resources the client can access on Integration Server. For more information about mapping scopes to clients, refer to Associating Scopes and Clients.

When a request is made to the authorization server, Integration Server verifies that the scope is defined for a client. The client is allowed to access only the namespace resources that are specified for the scope. If the requested scope is not defined, Integration Server returns an error indicating that the scope is invalid.

Adding a Scope

About this task

Complete the following steps to add a scope. The scope defines the services and folders that the clients are authorized to access.

To add a scope

Procedure
  1. Open the Integration Server Administrator if it is not already open.
  2. Go to Security > OAuth.
  3. Click Scope Management.
  4. Click Add Scope.
  5. Under Scope Configuration, specify the following information:
    Field Description
    Name Specifies a unique name for the scope. The scope name must consist of ASCII character codes in the range of 33 - 126, must be 100 characters or less, and cannot contain any of the following characters:

    \ , "
    Description A description of the scope.
    Note: If Integration Server generates the scopes automatically while creating the REST API descriptor based on the Swagger document, then Integration Server adds a default scope description as XX. You can modify this description; however, when Integration Server re-generates the RAD using the same Swagger document, Integration Server overrides the description as XX.
    Folders and services Specifies the list of folders and individual services that the client can access on behalf of the resource owner.

    You can add more than one folder or service at a time by specifying multiple lines, one folder or service to a line. Press Enter to separate lines.
    URL templates Specifies a URL template for a REST V2 resource that you want to secure using the scope.
    Note: If Integration Server generates the URLs automatically while creating the REST API descriptor based on the Swagger document, then Integration Server adds a default URL template as <HTTP method>_<REST API descriptor namespace>/<URL template of resource>. For example,

    GET_RadNamesSpace/employee.

    You can modify this template; however, when Integration Server re-generates the RAD using the same Swagger document, then it overrides the template as the default URL template.
  6. Click Save Changes.

Editing Scopes

About this task

Complete the following steps to edit a scope.

To edit a scope

Procedure
  1. Open the Integration Server Administrator if it is not already open.
  2. Go to Security > OAuth.
  3. Click Scope Management.
  4. Under Scope Configuration, click the Name for the scope that you want to edit.
  5. Update the information for the scope.
    Note: You cannot change the Name field for a scope.
  6. Click Save Changes.

Deleting Scopes

About this task

Complete the following steps to delete a scope.

Note: You cannot delete a scope that is used by a client. To see whether a scope is in use by a client, see Viewing Associations Between Clients and Scopes.

To delete a scope

Procedure
  1. Open the Integration Server Administrator if it is not already open.
  2. Go to Security > OAuth.
  3. Click Scope Management.
  4. Locate the scope in the Defined Scopes list, and click the Delete icon icon in the Delete column.
  5. When prompted to confirm that you want to delete the scope, click OK.

Associating Scopes and Clients

About this task

You manage the scope and client associations on the Associate Scopes to Clients page.

The Associate Scopes to Clients page is divided into two areas:

  • You can associate scopes to clients in the Scopes area (on the left). Use the Scopes area to make associations when you want to associate multiple clients to a single scope. This offers the advantage of adding or removing several associated clients for the scope at one time.
  • You can associate clients to scopes in the Clients area (on the right). Use the Clients area to make associations when you want to associate multiple scopes to a single client. This offers the advantage of adding or removing several associated scopes for the client at one time.
Note: You must define scopes and clients before you can associate them. For more information about registering clients, see Defining Clients. For more information about adding scopes, see Defining Scopes.

Adding Associations Between Clients and Scopes

About this task

Use the following procedure to add associations between scopes and clients.

To add associations between scopes and clients

Procedure
  1. Open the Integration Server Administrator if it is not already open.
  2. Go to Security > OAuth.
  3. Click Scope Management.
  4. Click Associate Scopes to Clients.
  5. If you want to associate one or more clients to a particular scope, do the following:
    1. Under Scopes, in the Select Scope list, select the scope to which you want to add an association to one or more clients.

      The Scopes area of the Associate Scopes to Clients page (on the left) contains two lists. Clients associated with Scope is a list of clients currently associated to the selected scope. Remaining Clients is a list of clients not currently in the selected scope.

    2. In the Remaining Clients list, select (highlight) the client or clients that you want to add to the scope.

      To select additional clients without deselecting currently selected clients, press the Ctrl key while you click the clients you want to select. To deselect a client, press Ctrl while you click the currently selected entry.

    3. After you have selected all the clients you want to add to the scope, click Left arrow icon. Integration Server moves the selected clients to the Clients associated with Scope list.
  6. If you want to associate one or more scopes to a particular client, do the following:
    1. Under Clients, in the Select Client list, select the client to which you want to add an association to one or more scopes.

      The Clients area of the Associate Scopes to Clients page (on the right) contains two lists. Scopes in this Client is a list of scopes currently associated to the selected client. Remaining Scopes is a list of clients not currently in the selected scope.

    2. In the Remaining Scopes list, select (highlight) the scope or scopes that you want to add to the client.

      To select additional scopes without deselecting currently selected scopes, press Ctrl while you click the scopes you want to select. To deselect a scope, press Ctrl while you click the currently selected entry.

    3. After you have selected all the scopes you want to add to the client, click Left arrow icon. Integration Server moves the selected scopes to the Scopes in this Client list.
  7. Click Save Changes.

Removing Client and Scope Associations

About this task
Use the following procedure to remove client and scope associations.
Note: Removing associations between scopes and clients does not delete the clients or scopes from the system, nor does it affect access tokens that have already been issued. For more information about deleting clients, see Deleting Clients. For more information about deleting scopes, see Deleting Scopes.

To remove client and scope associations

Procedure
  1. Open the Integration Server Administrator if it is not already open.
  2. Go to Security > OAuth.
  3. Click Scope Management.
  4. Click Associate Scopes to Clients.
  5. If you want to remove an association of one or more clients from a particular scope, do the following:
    1. Under Scopes, in the Select Scope list, select the scope for which you want to remove an association from one or more clients.
    2. In the Clients associated with Scope list, select (highlight) the client or clients that you want to remove from the scope.

      To select additional clients without deselecting currently selected clients, press Ctrl while you click the clients you want to select. To deselect a client, press Ctrl while you click the currently selected entry.

    3. After you have selected all the clients you want to remove from the scope, click Right arrow icon. Integration Server moves the selected clients to the Remaining Clients list.
  6. If you want to remove an association of one or more scopes from a particular client, do the following:
    1. Under Clients, in the Select Client list, select the client for which you want to remove an association from one or more scopes.
    2. In the Scopes in this Client list, select (highlight) the scope or scopes that you want to remove from the client.

      To select additional scopes without deselecting currently selected scopes, press Ctrl while you click the scopes you want to select. To deselect a scope, press Ctrl while you click the currently selected entry.

    3. After you have selected all the scopes you want to remove from the client, click Right arrow icon. Integration Server moves the selected scopes to the Remaining Scopes list.
  7. Click Save Changes.

Viewing Associations Between Clients and Scopes

About this task
Use the following procedure to view associations between scopes and clients.

To view the associations between clients and scopes

Procedure
  1. Open the Integration Server Administrator if it is not already open.
  2. Go to Security > OAuth.
  3. Click Scope Management.
  4. Click Associate Scopes to Clients.
  5. Do one of the following:
    • To view clients associated with a particular scope, under Scopes, in the Select Scope list, select the scope for which you want to view associated clients.
    • To view scopes associated with a particular client, under Clients, in the Select Client list, select the client for which you want to view associated scopes.

Managing Tokens

About this task

Use the Tokens page to view and remove the active tokens issued by the authorization server. Client applications use these tokens to access the resources on Integration Server (the resource server). When you delete the tokens, the client application can no longer access the resources owned by the resource owners.

You can also use built-in services include with the WmPublic package to revoke tokens issued by an Integration Server acting as an authorization server and remove expired access tokens.

Viewing Tokens

About this task
Use the following procedure to view the active tokens issued by the authorization server.

To view tokens

Procedure
  1. Open the Integration Server Administrator if it is not already open.
  2. Go to Security > OAuth.
  3. Click Tokens. Under Tokens, the Integration Server Administrator lists the active and expired access tokens issued by Integration Server.

Deleting Tokens

About this task
You can use the Tokens page to delete all active tokens. When you delete the token from the list of active tokens, Integration Server deletes both the access token and the refresh token. Keep the following points in mind when deleting tokens:
  • After you delete a token, other resource owners using the same client application can continue to do so. To keep a particular client application from accessing resources, you can disable or delete the client application. For more information about deleting client applications, see Deleting Clients.
  • Once a token is deleted, Integration Server rejects any requests from clients using that access or refresh token.

To delete tokens

Procedure
  1. Open the Integration Server Administrator if it is not already open.
  2. Go to Security > OAuth.
  3. Click Tokens.
  4. Locate the token in the Tokens list and click the Delete icon icon in the Delete column.
  5. When prompted to confirm that you want to delete the token, click OK.

Revoking Tokens

About this task
You can revoke a token issued by Integration Server using the pub.oauth:revokeToken service in the WmPublic package. The pub.oauth:revokeToken service revokes all of the tokens related to a specified token. If the token is an access token, the service revokes the associated refresh token as well. If the token is a refresh token, the service revokes the associated access token as well.

For more information about the pub.oauth:revokeToken service, see pub.oauth:revokeToken .

Removing Expired Access Tokens

About this task

To ensure that expired OAuth tokens are properly removed from the database and evicted from cache, Integration Server uses the Remove Expired Tokens system task to check for and remove expired OAuth tokens. The frequency with which the Remove Expired Tokens task runs and the number of expired tokens that the task removes is determined by the watt.server.oauth.token.removal.interval and watt.server.oauth.token.removal.maxRows server configuration parameters, respectively.

The Remove Expired Tokens system task executes the pub.oauth:removeExpiredAccessTokens service which deletes expired access tokens from the database by performing a series of delete operations in the database. The server configuration parameter watt.server.oauth.token.removal.batchSize controls the batch size for each delete and has a default value of 1000.

You can also invoke the pub.oauth:removeExpiredAccessTokens service in the WmPublic package directly to remove expired OAuth access tokens from the database. For more information about the pub.oauth:removeExpiredAccessTokens service, see pub.oauth:​removeExpiredAccessToken .

Note: The Remove Expired Tokens system task is available after applying a fix that includes PIE-79139 (IS_10.11_Core_Fix10).

Customizing the Approval Page

About this task

The approval page is an HTML page the authorization server sends to the resource owner after a client submits a request for access to their private resources. The resource owner uses the page to accept or deny the request.
Figure 5. OAuth approval default page
Default HTML page for OAuth approval

You can customize the title, logo, heading, and footer of the approval page using the watt.server.oauth.approvalpage properties. For information about using these properties, see Server Configuration Parameters.

About Using Integration Server as the Resource Server

When a client has requested access to a protected resource and has received an access token, the client can then present the access token to the resource server. If Integration Server is the resource server, clients can present the access token using the authorization request header field. Clients can send the access token in the Authorization request header field using the Bearer authentication scheme to submit the access token. For example:

GET /invoke/folder/svc HTTP/1.1    
Host: your-company.com:5555    
Authorization: Bearer access_token_id

If you are using the pub.client:http service, you can send the token using the auth header field. For information about using this service, see pub.client:http .

For more information about the Bearer authentication scheme, refer to the OAuth 2.0 Authorization Framework Bearer Token Usage specification.

Using an External Authorization Server

When Integration Server is the resource server, you must specify an authorization server. As an alternative to using an Integration Server as the authorization server, you can use a third-party server as the authorization server. This allows Integration Server to use OAuth bearer tokens created by a third-party OAuth 2.0 authorization server where the third-party vendor supports RFC 7662, OAuth 2.0 Token Introspection.

To use an external authorization server, you must:

  • Configure your third-party authorization server. This includes, but is not limited to, the following.
    • Create a client account that Integration Server will use to call the authorization server's introspection endpoint.

      Make a note of the client_id and client_secret values. You will provide this information as part of defining the external authorization server alias for the Integration Server resource server.

      Make a note of the URL for the introspection endpoint. You will provide this information as part of defining the external authorization server alias in the Integration Server resource server.

    • Create one or more OAuth scopes. These must match the names of the OAuth scopes you create in the Integration Server resource server.

    For more information on creating and configuring an OAuth 2.0 authorization server, consult the documentation provided by the vendor.

  • Configure an alias to the authorization server. For information, see Creating an External Authorization Server Alias.
  • Select the external authorization server alias as the Authorization Server value on the Security > OAuth > Edit Global Settings page.

Currently, Integration Server can be used with an external authorization server that supports RFC 7662, OAuth 2.0 Token Introspection, including:

  • Okta
  • Ping Identity
Note: When an access token from an external authorization server is rejected, information about the rejection is written to the server log. Set the OAuth logging facility (0010) to Debug to see these messages in the server log.

Creating an External Authorization Server Alias

About this task

If you want an Integration Server functioning as a resource server to use a third-party server as the authorization server, you must create an external authorization server alias.

To create an external authorization server alias

Procedure

  1. Open the Integration Server Administrator if it is not already open.
  2. Go to Security > OAuth.
  3. Click Add External Authorization Server.
  4. Under External Authorization Server Settings, provide the following information.
    Field Description
    Name Alias for the external authorization server. The following characters are prohibited: ? [ ] / \ = + < > : ; " , * | ^ @
    Introspection Endpoint The URL of the introspection endpoint for the external authorization server. Integration Server uses the introspection endpoint to determine if access tokens used in client requests are currently active.
    Client Id The ID of the user account that Integration Server uses when sending requests to the introspection endpoint of the external authorization server.
    Client Secret The password for the user account that Integration Server uses when sending requests to the introspection endpoint of the external authorization server.
    User The Integration Server user account that Integration Server uses to execute the client request. If the client is requesting a service, this is the user account that Integration Server uses to execute the service, which occurs after Integration Server calls the introspection endpoint. If the client is requesting a file, this is the user account that Integration Server uses to access the file.

    The User value is used only if the introspection endpoint of the external authorization server indicates that the access token is currently active.

    Click to search for and select your user. A user can be selected from the local or central directory.
    Keystore Alias (optional) The alias of the keystore on Integration Server  that holds the digital certificate that Integration Server sends to the external authorization server during the mutual (two-way) SSL handshake. You need to select a keystore alias only when the client account on the external authorization server is configured to use mutual (two-way) SSL.
    Key Alias (Optional) The alias of the Integration Server private key and associated digital certificate that Integration Server sends to the external authorization server during the mutual (two-way) SSL handshake. You need to select a key alias only when the client account on the external authorization server is configured to use mutual (two-way) SSL.
    Truststore Alias (Optional) The alias of the truststore on Integration Server that holds the Certificate Authority (CA) certificate of the external authorization server. You need to select a truststore alias only when all of the following are true:
    • The client account on the external authorization server is configured to use mutual (two-way) SSL, and
    • The authorization server’s Certificate Authority certificate is not in the set of well-known authorities trusted by the JVM in which Integration Server runs, and
    • The watt.security.cert.wmChainVarifier.trustByDefault property is set to false.
    Default Scope Default scope that takes effect when no scope is explicitly stated in the response from the external authorization server's introspection endpoint. Enter the scope values in this field exactly as they are defined on the external authorization server.

    When responses from an external authorization server's introspection endpoint do not return a scope value and a Default Scope is not specified, Integration Server considers requests bearing the access token from the authorization server to be out of scope and rejects the requests with a 401 response.
  5. Click Save.
    Integration Server Administrator displays the new external authorization server alias under External Authorization Servers on the Security > OAuth page.

Deleting an External Authorization Server

About this task

If you no longer need to use a third-party server as the authorization server for an Integration Server acting as the resource server, you can delete the external authorization server alias.

To delete an external authorization server alias

Procedure

  1. Open the Integration Server Administrator if it is not already open.
  2. Go to Security > OAuth.
  3. In the External Authorization Servers list, locate the external alias in and click the Delete icon icon in the Delete column.
  4. When prompted to confirm that you want to delete the alias, click OK.