Validating Third-Party Logons | Advanced SQL Engine 17.10 | Teradata Vantage - 17.10 - Validation by Token Exchanger - Advanced SQL Engine - Teradata Database

Teradata Vantage™ - Advanced SQL Engine Security Administration

Advanced SQL Engine
Teradata Database
Release Number
July 2021
English (United States)
Last Update

You can configure the JWT mechanism to accept JWT logons from third-party applications. For example, a user logs into a web app from a browser. The web app federates the logon to the customer's IdP. Then, if the user connects to Teradata Vantage the web app provides the JWT token to the Teradata server to successfully complete the logon.

By default, this feature is disabled.

To enable the feature, two identity providers are configured:

  • Internal IdP (called ping-internal in the example config file): Set Type to Ping-Federate and set ValidateByTokenExchange to no for the internal IdP.

    If the JWT is minted by this IdP, validation can be done without exchanging a token. In this case, the JWT is coming from an internal application.

  • External IdP (called keycloak21 in the example config file): Set Type to keycloak and set ValidateByTokenExchange to yes for the external IdP.

    If the JWT is minted by this IdP, first a token exchange is done, then the token is validated.

    In the TdgssUserConfigFile.xml, the <TokenExchanger> section has Ref set to ping-internal so it is pointing to the <IdentityProvider> section for the internal IdP, the one with Id set to ping-internal in this case.

To enable the internal IdP to accept JWT tokens from an external IdP:

  1. Make a backup copy of the /opt/teradata/tdat/tdgss/site/TdgssUserConfigFile.xml and save it according to your site standard backup procedures.
  2. Edit TdgssUserConfigFile.xml and configure the internal IdP and external IdP:
    <!-- JWT -->
     <!-- To modify JWT mechanism configuration, uncomment this section and edit -->
       <Mechanism Name="JWT">
               DatabaseName="${1}" />
               DatabaseName="${1}" />
               DatabaseName="${1}" />

    Where the <TokenExchanger> section properties are:

    Property Description
    Ref Refers to the internal identity provider configured. Ref is used to get the URL for the external Issuer of the JWT.
    ClientId The ID of the Gateway that is used during the token exchange.
    ClientSecret The Gateway Client secret password.

    If ClientSecretProtected is set to yes then ClientSecret is encrypted and saved.

    ClientSecretProtected Determines if the Gateway Client Secret is password protected.

    By default, this value is yes.

    Where the <IdentityProvider> section properties are:
    Property Description
    ValidateByTokenExchange Flag to indicate if a JWT coming from this Identity Provider needs to do a token exchange for validation.

    Valid values are Yes or No.

    Set to No by default.

    [Optional] SubjectIssuer The alias name by which the external IdP (the access token issuer) is registered with the internal IdP.

    This parameter is optional if Ping-Federate is the internal IdP.

    SubjectIssuer is needed if Keycloak is the internal IdP.

    Id Uniquely identifies the IdP in the configuration file.
    Url URL of the IdP. From the URL, TDGSS can issue REST API calls to get the required URLs and other information, such as Issuer, JWK URI, and so on.

    This URL is not related to IdpUrl in the <GlobalValues> section.

    It is required to use secure https URLs.
    Type The type of the Identity Provider. Example values are: Ping-Federate, keycloak, vantage-keycloak, azuread, okta, and auth0.

    Different identity providers may supply usernames in different formats. <UserNameMapping> provides the expected patterns for usernames, so JWT can extract usernames from the payload.

    The <UserNameMapping> section properties are:
    Property Description
    Claim Claims are a portion of the payload that contain information about the user, among other things.
    Match The pattern the claim is matched to. For example, if the claim contains a sub (subject), that sub is parsed by the pattern so that a valid database username can be extracted from it.
    DatabaseName The portion of the claim that is extracted and is used as the database logon username for the user.

    For more information about user name mapping, see User Name Mappings.

  3. Place the CA certificates in the location specified in JWTClientTlsCACertDir. This directory is typically here: /opt/teradata/tdat/tdgss/site/ssl/cacerts.
  4. Verify the configuration is correct:
    1. Run tdgsstestcfg to verify the new configuration is correct. It launches a test environment in a new shell that contains the updates to the configuration file.
    2. Test the configuration with the tdgssauth tool:
      tdgssauth -m JWT -a token=JWT_from_IdP

      Where JWT_from_IdP is the IdP you configured in TdgssUserConfigFile.xml. You can run the command multiple times to test the configuration for each IdP configured.

    3. Exit the test shell:
    4. Continue editing and testing until the configuration is correct.
  5. Run:
  6. If run_tdgssconfig indicates that a TPA reset is required, run:
    tpareset -f “use updated TDGSSCONFIG GDO”