Configuring a native OAuth provider

Native OAuth providers are configured and managed by you within your cloud.

About this task

A native OAuth provider object provides settings for OAuth processing operations such as generating and validating OAuth tokens. An OAuth provider object is referenced by an OAuth security definition to protect an API. When a native OAuth provider is used, the OAuth operations are performed natively by API Connect.

Every OAuth provider object has a backing API. Your configuration here automatically updates the OpenAPI document of the API. You can edit the OpenAPI document directly by navigating to the Resources icon Resources > OAuth Providers page, selecting your OAuth provider, then clicking API Editor.

Note: Take care when modifying the code directly on the Source tab of the API Editor because validation is limited. For example:
  • If you change the name of auto generated assembly actions in the source code, the assembly will be prevented from updating dynamically when the OAuth provider settings are modified.
  • You must ensure that the OAuth provider name matches the value specified in the oauth-provider-settings-ref field in each OAuth assembly action.

When a published API references an OAuth provider object, the backing API is automatically made available in the gateway.

Token requests and client_id checks:
If you are calling an OAuth endpoint, the sequence of client_id checks in the token request is as follows:
  1. Check both body and query.
    • If found in only the body, validate and return a 200 or appropriate return code.
    • If found in only the query, return a wrong location error.
    • If found in both the body and the query, return a more than one location error.
  2. When not found in the body or the query, check the Authorization header.
    • If found in this header, validate and return a 200 or appropriate return code.
  3. Not found, return the appropriate error and code.
The best location for the client_id is in the request body.

One of the following roles is required to configure a native OAuth provider:

  • Administrator
  • Owner
  • Topology Administrator
  • Custom role with the Settings:Manage permissions
Note:
  • The OAuth provider logs analytics data for failure cases, but does not log successful cases. Activity log policies that call for logging of analytics data upon success do not apply for the OAuth provider.
  • You must ensure the OAuth Provider is configured in the Sandbox Catalog before using the OAuth Provider in a non-Sandbox Catalog.

Procedure

OAuth provider configuration uses a series of screens. The first set of screens controls a basic OAuth provider configuration. Perform the following steps to configure a native OAuth Provider for your cloud:

  1. In the Cloud Manager, click Resources iconResources.
  2. Click OAuth Providers > Add > Native OAuth provider.
    1. Complete the following parameters for the first screen, then click Next.
      Field Description
      Title Enter a title for the native OAuth provider.
      Name This field is auto-populated by the system.
      Description (optional) Enter a brief description.
      Base path (optional) The base path is the URL segment of the API that is shared by all operations in the API. It does not include the host name or any additional segments for paths or operations. The base path cannot include special characters and must begin with a "/" character even if it is otherwise empty.
      Gateway Type Select the gateway type, either DataPower® Gateway (v5 compatible) or DataPower API Gateway.

      For information about types of gateways, see API Connect gateway types.

      OAuth Providers apply to one gateway type.
    2. In the next screen, enter the following additional configuration parameters, then click Next.
      Field Description
      Authorize Path /oauth2/authorize/ is the standard OAuth endpoint to login to account
      Token Path /oauth2/token/ is the standard OAuth endpoint to exchange code for access token.
      Supported grant types
      • Implicit - An access token is returned immediately without an extra authorization code exchange step.
      • Application - Application to application. Corresponds to the OAuth grant type "Client Credentials." Does not require User Security.
      • Access code - An authorization code is extracted from a URL and exchanged for an access code. Corresponds to the OAuth grant type "Authorization Code."
      • Resource owner - Password - The user's username and password are exchanged directly for an access token, so can only be used by first-party clients.
      • DataPower API Gateway onlyResource owner - JWT - A verified signed JSON Web Token is exchanged directly for an access token.
        Note: To use the Resource owner - JWT option, complete the following steps:
        1. In the Supported grant types field, select both Resource owner - Password and Resource owner - JWT.
        2. Edit the API definition and add a security scheme that specifies oauth2 as the security definition type and select Resource owner - Password as the flow type.

          For instructions on defining an OAuth2 security scheme for an API, see Defining OAuth2 security scheme components (OpenAPI 3) or Defining OAuth2 security schemes (OpenAPI 2).
      Supported client types
      • Confidential - Client can maintain secure credentials on a secure server
      • Public - Client credentials are not secure.
    3. Enter the scopes in the next screen. A scope becomes an option in the request and response for an access token. Click Add to add additional fields for scopes. Click Next when done.
      Field Description
      sample_scope_1 Scope for token
      additional scopes Scope for token
    4. Enter the parameters for User Security in the next screen. Define the settings to use to extract the application users’ credentials, authenticate their identities, and grant authorization. User Security is not required for the Application grant type. Click Next when done.
      Field Description
      Identity Extraction Determines how the user credential is extracted:
      • Basic Authentication - HTTP basic authentication (requires no additional configuration)
      • Default HTML Form - Use default login form for user name and password
      • DataPower API Gateway onlyContext variable - Specify which variable contains the user name and password. API Connect OAuth context variables as listed here API Connect context variables

        Note: DataPower API Gateway only. Not available for DataPower Gateway (v5 compatible).

      • Custom HTML Form - Enter the endpoint and select an optional TLS profile for a custom HTML form. For instructions on creating a custom form, see Creating a custom HTML login form for user security.
      • Redirect - If you select Redirect , enter the following parameters:
        • End Point - Enter an endpoint to redirect to a third-party identity provider. For more information, see Authenticating and authorizing through a redirect URL
        • Optional: Query parameters - Enter the query parameters. Query parameters are part of the URL come after the question mark symbol (?), usually consisting of key-value pairs separated by ampersand symbol (&).
          Note: To ensure the query parameters that you entered is applied to the gateway, republish your OAuth provider.
        • Redirect time limit - The user must verify their identity and return to the main authorization process within the specified redirect time limit. If the user exceeds this time limit, the process might fail or restart. The default redirect time limit is 300. You can adjust this duration based on your requirements.
      • DataPower API Gateway onlyDisabled - do not collect the user credential
      Note: If you use either the Default HTML Form or Redirect identity extraction methods, the response from the redirect endpoint must maintain the order of the query parameters before the state_nonce query parameter, otherwise the authorization fails.
      Authentication Authenticate application users with a user registry. Select an LDAP or Authentication URL user registry or create the SampleAuthURL User Registry. For a DataPower API Gateway, you have the option to disable authentication with a user registry.
      Authorization The following methods for extracting the user credential are available:
      • Authenticated - Authorize authenticated users automatically.
      • Default HTML Form - Use default HTML form to authorize.
      • Custom HTML Form - Enter the endpoint and select an optional TLS profile for a custom HTML form. For instructions on creating a custom form, see Creating a custom HTML authorization form for user security.
      • DataPower API Gateway onlyDisabled - Disable authorization.
  3. Review the Summary for the native OAuth provider configuration.
  4. Click Back to make changes.
  5. Click Finish to save the basic configurations and to proceed to the Advanced Parameters for a native OAuth Provider.

    If you want to specify the native OAuth Provider in your Catalog, see Specifying the OAuth Providers.

Results

Depending upon the visibility setting, the OAuth Provider can be used to secure the APIs in catalog.