Setting up token authentication

First, you set API default configurations. The settings allow Trust Protection Platform Authentication Server to manage tokens. Next, you register and specify scopes for each application. The settings match all of the scopes that your application uses. Last, make an Authorize call to get token. The token must go in the header of every API call you make.

Did You Know?
The VEDAuth server uses the OAuth 2.0 principles to manage tokens and grants. During installation, the VEDAuth server automatically enables as an IIS service.

To set up for token authentication

  1. (Optional) Configure IIS Manager to accept certificate authentication for Remote Web SDK clients. Recommended for POST Authorize/Certificate.
  2. From the Platform product menu, click API Default Settings.
  3. Expand the Tokens panel, and confirm or update the following values as appropriate:

    Token Auth Configuration Settings

    Field

    Description

    Refresh Token

    Refresh settings:

    • Enabled: Default. Receive a refresh token with the request for a bearer access token. Prior to the Token Validity day, you can send the refresh token to the VEDAuth server to get a new bearer access token.

    • Disabled: At the time when the VEDAuth server issues a bearer access token, no refresh token is supplied. The validity period is determined by the application's grant validity.

    Token expires after

    The period of time that the bearer access token is valid before rotation is required. The default is 90 days.

    Access expires after

    The maximum time that an authorization grant for the Token Auth scope is valid. If the Refresh Token is enabled, you can continue to get new tokens until the token and grant expire. The default is 1 year.

  4. Expand the Session cache panel and confirm or update the following values as appropriate.

    Session cache configuration settings

    Field

    Description

    Expiration Mode

    Expiration mode settings:

    • Normal. (Default) Credentials will be cached for better performance. Cache will refresh with the Session expiration setting, described below.

    • Strict. Credentials will be verified on every API call, requiring an extra call to the database for every call, thus costing performance. (Internal testing at Venafi suggests response time can be 40% longer when using Strict mode.)

    Session Pool Size (sessions)

    The number of concurrent sessions for API calls. The default is 5000. If the number of simultaneous API calls exceed the pool size, the oldest unused session is removed from the pool.

    Session Expiration (minutes)

    The number of minutes each token remains in memory. The default is 1440, which is 24 hours.

    Allowed Authentication Methods

    Authentication

    Trust Protection Platform Authentication Server setting

    Username & Password The client passes a user name and password to the VEDAuth server. Recommended for POST Authorize/OAuth.
    Integrated MS Windows Authentication Default. The client passes Windows credentials to the VEDAuth server.

    Browser-based authentication

    Default. Required for POST Authorize/Device. Recommended for multi-factor SAML authentication:

    • Enabled: Default. Allow multi-factor authentication for devices. A successful response, includes a web link to complete the authentication.
    • Disabled: Block browser-based authentication.

    JSON web token

    A token in JSON format that is used to communicate between a trusted identity provider and Venafi Platform.

    Certificate

    The caller passes a client certificate to the VEDAuth server. When selected, the Use AD Security Identifier (SID) value if available option appears.

    AD Security Identifier (SID)

    If you select Certificate, the Use AD Security Identifier (SID) value if available option appears. In this scenario, AuthServer follows a specific process. First, it looks for the SID Extension value in the certificate. If the SID Extension is found, AuthServer tries to find the matching AD user. However, if the SID Extension is not in the certificate or doesn't match an AD account, AuthServer will then use the "Location" setting as a backup.

  1. (Optional) Complete the Certificate Authentication section:

    Certificate Authentication Settings

    Field

    Parameter

    X.509 Identity Field

    The field for Trust Protection Platform Authentication Server to use as the user identity:

    • SubjectAltName: UPN: The identity that also has access to the Web SDK.
    • SubjectAltEmail: The email address (es).
    • CN: The certificate name (CN). For local identities, always specify CN.
    Trusted Certificate Authorities The CA(s) that are approved to issue client certificates for authentication. Select a Trusted Certificate Authority certificate from the Roots tree.
    AD Security Identifier (SID) The certificate is mapped to the Active Directory User’s SID (objectSid).
  2. Click Save.
  3. Either wait 10 minutes or remote into the server and from the command line, type iisreset.
  1. Find the scopes that your application needs in the Scope map for tokens.
  2. From the Platform menu bar, click APIIntegrations, register and set scopes for your application. For more information, see Integrating other systems with Venafi products.

    TIP  Set all of the scopes that your integration requires.

    Scope definitions match application scopes

  3. To get a token, call an Authorize method with the values you just defined. For more information, see Getting a token.