Configure OAuth server using Authorization code grant type

The Authorization code grant type is used to obtain access tokens and refresh tokens from the authorization server and is optimized for confidential clients.

Kofax TotalAgility supports the Authorization code grant with a refresh token grant which means, you should generate access and refresh tokens at design time. TotalAgility uses a refresh token to regenerate the access token; it does not require manual intervention.

  1. Navigate to Integration > OAuth servers.

    The OAuth servers page appears.

  2. Click New.

    The New OAuth server configuration dialog box is displayed. By default, the General tab is open.

  3. Configure the following properties.

    General properties

    Name

    A globally unique name for the OAuth server.

    The name can have a maximum of 50 characters.

    Category

    By default, the system automatically saves a new OAuth server in your working category. To store it in a different category, select a category.

    Grant type

    Authorization code.

    Authentication method

    Specify the authentication methods to add additional security to an authorization grant. The following methods are available:

    See Authentication methods for a description of fields specific to an authentication method.

    Client ID

    An ID to identify the client. The ID must be an alphanumeric string.

    Client secret

    To log in, select either option:

    • Local: Enter the secret string that the client uses.

    • External: Enter the secret string stored in the configured external storage.

    Access token URL

    The URL to get an access token.

    Scope

    The scope to restrict access to specified areas.

    The value of the scope must be defined as a list of space-delimited and case-sensitive strings.

    Authorization code URL

    The URL to get an authorization code from the authorization server.

    Redirect URI

    If the authorization server is configured to redirect to this preset Kofax TotalAgility Administrator's Guide URI, the authorization code is automatically extracted and used for the token generation process.

    If this option is clear, the preset URL is displayed in the Redirect URI field in read-only mode and the authorization code is automatically extracted

    Use custom redirect URI

    Select this option to specify a custom redirect URI which the authorization server is configured with.

    When the authorization server redirects to this URI, copy the entire authorization code from the URI and paste it into the Authorization code URL field.

    Use state

    If this option is selected, a random string is generated by the application, which is verified while receiving authorization. (Default: Selected)

    Use PKCE

    If the authorization server supports PKCE (Proof Key for Code Exchange), selecting this option prevents the interception of the authorization code and several other attacks.

    Supports refresh token

    If this option is selected, the Authorization server supports refresh token generation.

    This option is read-only and always selected for the authorization code grant. (Default: Selected)

    Refresh token validity duration

    The duration for which the token should remain valid. If set to zero, the refresh token always remains valid. (Default: 0)

    Additional properties

    Access token request

    You can exclude or include the following parameters when sending the access token request:

    • Include scope (Default: selected)

    • Include redirect URI (Default: selected)

    Maximum retry attempts

    The maximum number of retry attempts to acquire an access token. (Default:3)

    Maximum wait duration

    The maximum wait duration to acquire an access token. (Default:1 minute)

    Query parameters

    The query parameters (if any) required by the authorization server, for access token requests. To add query parameters:

    1. Click .

    2. Provide a Name and Value.

    3. Click Add.

    Post parameters

    The post parameters (if any) required by the authorization server, for access token requests. To add post parameters:

    1. Click .

    2. Provide a Name and Value.

    3. Click Add.

  4. Click Authorize.

    The authorization server login page appears in a new browser and either of the following occurs depending on the URI configuration.

    • If the authorization server is configured to redirect to preset Kofax TotalAgility Redirect URI, the authorization code is automatically extracted and used for the token generation process.

    • If the authorization server is configured to redirect to a custom URI, you must copy the entire URL from the address bar of the browser and paste it into the Authorization code URL field. Any query parameters required by the authorization server should be included here.

    The authorization button is disabled until the authorization is complete and TotalAgility Designer has extracted the authorization code.
  5. Click Save to get access and refresh tokens.

    The authorization server exchanges the authorization code for access and refresh tokens.

    • If the token generation fails, an error message is displayed; however, the configuration details are saved for reuse.

    • When you edit an OAuth server using Authorization code grant type that has already been authorized you need to authorize again.