16.20 - Working with JWT Authentication - Teradata Vantage NewSQL Engine

Teradata Vantage™ NewSQL Engine Security Administration

prodname
Teradata Database
Teradata Vantage NewSQL Engine
vrm_release
16.20
created_date
March 2019
category
Administration
Security
featnum
B035-1100-162K

Configuring Teradata Database Servers for JWT Authentication

The JSON Web Token (JWT) authentication mechanism enables single sign-on (SSO) to the Teradata Database after the user successfully authenticates to Teradata UDA User Service. The UDA User Service authenticates users to various UDA applications and services, such as Teradata AppCenter and the Teradata® Query Service (REST services). JWT allows a user that has been authenticated to one of the applications or services to do a single sign-on to establish a session with the Teradata Database.

Complete the following setup to enable the use of JWT authentication:

  1. Get the decryption and verification keys from the UDA User Service by calling Teradata® Query Service (REST APIs). This can either be done through the service’s built in Swagger UI browser interface or by using cURL commands. By default, the Swagger UI endpoints are configured to be blocked, so the recommended method is to use cURL.

    The following commands can be used to authenticate and retrieve the keys. Do the following from a database node that has access to the UDA User Service:

    1. Authenticate as an Admin user and get a JWT:
      curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' -d '{ \ 
         "password": <PW>, \ 
         "username": <USERNAME> \ 
       }' 'https://<server_name>:<port_num>/token'
      
    2. Get the decryption key:
      curl -X GET --header 'Accept: text/plain' --header 'Authorization: Bearer <MY JWT TOKEN>' 'https://<server_name>:<port_num>/decryptionKey'
      
    3. Get the signature (verification) key:
      curl -X GET --header 'Accept: text/plain' --header 'Authorization: Bearer <My JWT TOKEN>' 'https://<server_name>:<port_num>/signatureKey'
      

      Where <server_name> is the server running the UDA User Service and <port_num> is the port number of the UDA User Service.

      The port number (<port_num>) is configurable. For the RPM version of the user service it is usually 8001. Replace <port_num> in the example commands with the port number for your configuration.
    4. Save the key files to any file name and in any location. The decryption and verification key files should have a .pem extension and should contain a header and a footer.

      For example, the decryption key is similar to this:

      # cat decryption_key.pem
      -----BEGIN RSA PRIVATE KEY-----
      MIICXgIBAAKBgQCdx3v70O97sQ4retwU54YFp+khWhqZ4qZ0ekUTz/9T9a36bbX6
      2TnRTR/59tkITiu5mPwQCoAvL9DZNJWUUpzjugWjZGzBHlCFfKe3KTnhw6IXNnHb
      PJV7b5vunaoDt+iur+MkKcgj0i+4G/mmXUk/rIFiLJQtWVr4Coj3jYj+NQIDAQAB
      AoGBAIBnMyCJNgys2AJMl0Uv8mMx9kldQd7QlHSgeQ0ZrgpPG4p9tKb0F9ic8pQD
      7zaSH4WI2kHXueAtAsNxxvWRkfl7pzVjUMrIqwnivkNFTY4iPzJeRw/3KLxhlgfv
      Q7l+CMprKnLuscl9Dt9oR4+Ypm745yPJ+6ZnHJyvXELPU0rVAkEA6fhqcumIEOsJ
      TU+Lo94xKngXHS4ms9dND0xZEhPImTXz4YPWCCwX11d6wII2Tz3k+LTQ/I/2rqy8
      9DXpwBs4hwJBAKyikc9jvEEHfeUNNymjf5Bg9eRVnzPaq6QitTaXvT/zPgjElOFh
      GpADP7fUiUR4PtocZ47Q8co+jIMR8XEvTmMCQQC3SjmyLgq/HjGaVB+Tz0P6/js1
      S+tb5eXjfy8j/0Wd6OtWlt48ZraCp3BtkVSUfWt7/sLdqLZans4kDnxBV9HPAkEA
      qNzoNW1AUneqjKdNovwbpjVBsJSUAlvN8uJEUV9BrdEXh+oKGx8ppV6YMA/EKWZZ
      TG3mWgtFx2dBeF/PxL/aMwJAWepYUPkM3MReuAp7oij4qIrOq9xPpHlO4+kBKMWp
      yR6wvSLqDxSX3erkBq6Eh39BMchta3clU7PXck4pKrDf0A==
      -----END RSA PRIVATE KEY-----
      

      For example, the verification key is similar to this:

      # cat verification_key.pem
      -----BEGIN PUBLIC KEY-----
      MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCdx3v70O97sQ4retwU54YFp+kh
      WhqZ4qZ0ekUTz/9T9a36bbX62TnRTR/59tkITiu5mPwQCoAvL9DZNJWUUpzjugWj
      ZGzBHlCFfKe3KTnhw6IXNnHbPJV7b5vunaoDt+iur+MkKcgj0i+4G/mmXUk/rIFi
      LJQtWVr4Coj3jYj+NQIDAQAB
      -----END PUBLIC KEY-----
      
  2. (For multi-node installations) Securely transfer the keys to the other database nodes. Check the permissions of the key files to make sure the Teradata Database can access them. To transfer the keys, do the following:
    1. Log on to the database node that contains the keys.
    2. Move the keys to the other database nodes:
      pcl -send <location>/<decryption_key_file_name> <location>/<decryption_key_file_name>
      
      pcl -send <location>/<verification_key_file_name> <location>/<verification_key_file_name>
      Store the decryption and verification key files in the same location on all the nodes.
  3. Edit the TdgssUserConfigFile.xml and uncomment the following section:
    <!-- JWT -->
    <!-- To modify JWT mechanism configuration, uncomment this section and edit
            <Mechanism Name="JWT">
                <MechanismProperties
                    MechanismEnabled="yes"
                    DefaultMechanism="no"
    
                    JWTDecryptionKeyFile=""
                    JWTVerificationKeyFile=""
                    JWTSkewTime="300"
                    />
    </Mechanism>
    (end of commented out section)-->
    
  4. Set JWTDecryptionKeyFile to the absolute path to the file containing the decryption key.
  5. Set JWTVerificationKeyFile to the absolute path to the file containing the verification key.
  6. Optional. Edit and set JWTSkewTime. JWTSkewTime is the number of seconds a JWT will be still valid after its expiration.
  7. Save the file.
  8. Run the run_tdgssconfig utility to update the TDGSSCONFIG GDO:
    /opt/teradata/tdgss/bin/run_tdgssconfig
  9. Run tdgssfixpaths to set the owner and permissions on the JWTDecryptionKeyFile and JWTVerificationKeyFile:
    psh 'perl /opt/teradata/tdgss/bin/tdgssfixpaths'
  10. Run tpareset to activate the changes to the TDGSS configuration:
    tpareset

Example: Using JDBC to Connect to JWT

Programmatically connect to JWT through JDBC:

jdbc:teradata://<system_name>/LOGMECH=JWT,LOGDATA=”token=<JWT of user>”

Where:

  • <system_name> is the Teradata Database system name
  • LOGMECH is set to JWT (the mechanism name)
  • <JWT of user> is the value of the user's token and is similar to:
    eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWV9.TJVA95OrM7E2cBab30RMHrHDcEfxjoYZgeFONFh7HgQ

Related Information

For more information about JWT, see https://tools.ietf.org/html/rfc7519.

For more information about configuring JWT, see JWT Mechanism and JWT Support Properties.

For information about connectivity from clients, see: