set_auth_token | Set Authentication Token | Open Analytics Framework - set_auth_token - Teradata Package for Python

Use set_auth_token() to manage the authentication token required to access services running on VantageCloud Enterprise. This method supports PAT/JWT authentication, Basic authentication, and multiple OAuth 2.0 flows provided by multiple Identity Providers (Keycloak, Ping Federate).

Use set_auth_token() to generate and set the authentication token required to access services running on VantageCloud Lake.

Arguments that Support Authentication Mechanisms and Flows

Required Parameters

base_url

Specifies the endpoint URL for a given environment in VantageCloud Lake.

pem_file

Required, if PAT authentication is to be used, optional otherwise.

pat_token

Required, if PAT authentication is to be used, optional otherwise.

Optional Parameters

client_id

Specifies the id of the application that requests the access token from VantageCloud Enterprise or other OAuth based identity providers (IDPs).

• Teradata recommends explicitly providing this argument to avoid ambiguity.
• For VantageCloud Enterprise: If not specified with OAuth flows, it will be derived from "base_url".
• Required for OAuth based authentication with explicit IDP configuration.

Typically, it has the format client_id = <org_name>-oaf-device. You can get the organization name from the URL used to access the VantageCloud Lake Console. For example, https://organization_name.innovationlabs.teradata.com.

**kwargs

username

Required if create_context() is not called before set_auth_token().

Specifies the user for which authentication is to be requested.

If not specified, then user associated with current connection is used.

• Use this option only if name of the database username has lower case letters.
• Required for OAuth password grant and Basic authentication flows.

Use this option only if name of the database username has lower case letters.

password

Specifies the password for database user.

• Required for Basic authentication mechanism.
• Required for OAuth password grant flow.
• Required for KeyCloak authentication.

expiration_time

Specifies the expiration time of the token in seconds. After expiration time, JWT token expires and UserEnv methods do not work, and you need to regenerate the token.

This option is used only for PAT and not for OAuth.

Default value: 31536000

auth_token

Specifies the authentication token required to access services running on VantageCloud Enterprise.

• If "auth_token" is set through this class, then this class should always be used only after create_context().
• Use this option only if user has JWT token and wants to set the same instead of generating it again from this class.

kid

Specifies the name of the key which is used while generating 'pem_file'.

Use this option only when key used during the pem file generation is different from pem file name. For example, if you use the key as 'key1' while generating pem file and the name of the pem file is 'key1(1).pem', then pass value 'key1' to the argument "kid".

auth_url

Specifies the endpoint URL for a keycloak server.

rest_client

Specifies the service for which keycloak token is to be generated.

• Teradata recommends using "client_id" argument along with "auth_mech" as 'OAUTH' and "idp_type" as 'KEYCLOAK' when keycloak IDP is paired with "oauth_grant_type".
• This argument is kept for backward compatibility when "auth_mech" is 'KEYCLOAK'.

Permitted values: "VECTORSTORE"

Default value: "VECTORSTORE"

auth_mech

Specifies the mechanism to be used for generating authentication token.

• Teradata recommends explicitly providing this argument to avoid ambiguity.
• When "auth_mech" is provided, other arguments are used in the following combination as per value of "auth_mech":
  • OAuth: Token generation is done through OAuth (device flow or password grant based on "oauth_grant_type") by using client id which can be specified by user in "client_id" argument or can be derived internally from "base_url" in VantageCloud Enterprise.
  • PAT : Token generation is done using "pat_token" and "pem_file".
  • BASIC: Authentication is done via Basic authentication mechanism using user credentials passed in "username" and "password" arguments.
  • JWT : Readily available token in "auth_token" argument is used.
  • KEYCLOAK: Token generation is done via keycloak IDP. It's a variant of OAuth only. This is kept for backward compatibility. When keycloak IDP is used, Teradata recommends using "auth_mech" as 'OAUTH' with "idp_type" as 'KEYCLOAK' instead of using 'KEYCLOAK' as value for "auth_mech" argument.

When "auth_mech" is provided, other arguments are used in the following combination as per value of "auth_mech":

• OAuth: Token generation is done through OAuth by using client id which can be specified by user in "client_id" argument or can be derived internally from "base_url".
• PAT : Token generation is done using "pat_token" and "pem_file".
• BASIC: Authentication is done via Basic authentication mechanism using user credentials passed in "username" and "password" arguments.
• JWT : Readily available token in "auth_token" argument is used.
• KEYCLOAK: Token generation is done using keycloak.

Permitted values: "OAUTH", "PAT", "BASIC", "JWT", "KEYCLOAK".

validate_jwt

Specifies whether to validate generated JWT token or not.

Applicable only when "auth_mech" is "PAT".

Default value: True

valid_from

Specifies epoch seconds representing time from which JWT token will be valid.

Applicable only when "auth_mech" is "PAT".

Default value: 0

oauth_grant_type

Specifies the OAuth 2.0 grant type to use for authentication.

• Determines the OAuth flow to be used.
• If not specified, defaults to 'device_code' flow for OAuth.
• Refresh tokens are automatically handled within 'device_code' and 'password' flows.

Permitted values: "PASSWORD", "DEVICE_CODE"

Default value: "DEVICE_CODE"

idp_type

Required when "auth_mech" is 'OAUTH' and IDP is other than VCL internal provider.

Specifies the Identity Provider (IDP) type for OAuth flows.

• Teradata recommends explicitly providing this argument to avoid ambiguity in IDP derivation.
• Determines which IDP configuration to use.
• Different IDPs may have different endpoint structures.

Permitted values: "KEYCLOAK", "PING", "VCL_IN_HOUSE".

Default value: "VCL_IN_HOUSE"

oidc_issuer_url

Specifies the base URL of the Identity Provider which is further appended with ".well-known/openid-configuration" for OIDC endpoint discovery in OAuth flows. For example:

• If the IDP is keycloak and its base URL is "https://aiop-abcd.td.teradata.com", then the OIDC issuer URL will be "https://aiop-abcd.td.teradata.com/sso/realms/[realm_name]", where IDP is hosted.
• If the IDP is Ping and its base URL is "https://tdicam1111dv11.teradata.com/", then the OIDC issuer URL will be "https://tdicam1111dv11.teradata.com".
• If the IDP is VCL in-house and the base URL is "https://vectorstoreawssite.teradata.com", then the OIDC issuer URL will be "https://vcl-idp.td.com/auth".

If not specified, it will be derived from "base_url" and "idp_type".

idp_username

Specifies the IDP username for OAuth password grant flow.

• If not specified, defaults to the value of "username" parameter.
• Use this when IDP username differs from database username.

idp_password

Specifies the IDP password for OAuth password grant flow.

• If not specified, defaults to the value of "username" parameter.
• Use this when IDP username differs from database username.

keycloak_realm

Specifies the Keycloak realm name when using Keycloak IDP.

• Required when "idp_type" is 'KEYCLOAK' and realm is non-default.
• Used to construct OIDC issuer URL when "oidc_issuer_url" is not provided.

Default value: "teradata"

oauth_scope

Specifies the OAuth 2.0 scopes to request during authentication.

Scopes define the level of access and permissions granted by the access token.

Multiple scopes should be space-separated (e.g., 'openid profile email').

• Only applicable when using OAuth or Keycloak authentication mechanisms.
• The 'openid' scope is required for OpenID Connect flows.
• Different Identity Providers may support different scopes.
• Follows OAuth 2.0 RFC 6749 specification for scope format.

Default value: "openid"

This class returns True if the operation is successful.

Example 1: Set the Authentication Token Using Default client_id

>>> import getpass

>>> set_auth_token(ues_url=getpass.getpass("ues_url : "))

Authentication token is generated and set for the session.

Example 2: Set the Authentication Token by Specifying the client_id

>>> import getpass

>>> set_auth_token(ues_url=getpass.getpass("ues_url : "),
...                client_id=getpass.getpass("client_id : "))

Authentication token is generated and set for the session.

Example 3: Set the Authentication Token by Specifying the pem_file and pat_token without specifying "username"

>>> import getpass

>>> set_auth_token(ues_url=getpass.getpass("ues_url : "),
...                pat_token=getpass.getpass("pat_token : "),
...                pem_file=getpass.getpass("pem_file : "))

Authentication token is generated and set for the session.

Example 3: Set the Authentication Token by Specifying the pem_file and pat_token

>>> import getpass

>>> set_auth_token(ues_url=getpass.getpass("ues_url : "),
...                pat_token=getpass.getpass("pat_token : "),
...                pem_file=getpass.getpass("pem_file : "))

True

Example 4: Set the Authentication Token by Specifying pem_file and pat_token and username

>>> import getpass

>>> set_auth_token(ues_url=getpass.getpass("ues_url : "),
...                pat_token=getpass.getpass("pat_token : "),
...                pem_file=getpass.getpass("pem_file : "))
...                username=getpass.getpass("username : "))

Authentication token is generated and set for the session.

Example 4: Set the Authentication Token by Specifying the pem_file and pat_token and username

>>> import getpass

>>> set_auth_token(ues_url=getpass.getpass("ues_url : "),
...                pat_token=getpass.getpass("pat_token : "),
...                pem_file=getpass.getpass("pem_file : "))
...                username = "alice")

True

Example 5: Set the Authentication Token by Specifying the pem_file and pat_token and kid

>>> import getpass

>>> set_auth_token(base_url=getpass.getpass("base_url : "),
...                pat_token=getpass.getpass("pat_token : "),
...                pem_file=getpass.getpass("pem_file : ")
...                kid="key1")

Authentication token is generated, authenticated and set for the session.

Example 5: Set the Authentication Token by Specifying the pem_file and pat_token and username and kid

>>> import getpass

>>> set_auth_token(base_url=getpass.getpass("base_url : "),
...                pat_token=getpass.getpass("pat_token : "),
...                pem_file=getpass.getpass("pem_file : ")
...                kid="key1")

Authentication token is generated, authenticated and set for the session.
True

Example 6: Set the Authentication Token using Basic Authentication Mechanism by Specifying the base_url, username, and password

In this example, "auth_mech" is defaulted to 'BASIC' as "username" and "password" are provided.

>>> import getpass

>>> set_auth_token(base_url=getpass.getpass("base_url : "),
...                username=getpass.getpass("username : "),
...                password=getpass.getpass("password : "))

Authentication token is generated and set for the session.

Example 6: Set the Authentication Token using Basic Authentication Mechanism by Specifying the base_url, username, and password

>>> import getpass

>>> set_auth_token(base_url=getpass.getpass("base_url : "),
...                username=getpass.getpass("username : "),
...                password=getpass.getpass("password : "))

Authentication token is generated, authenticated and set for the session.
True

Example 7: Use an existing JWT token

In this example, "auth_mech" is defaulted to 'JWT'.

>>> import getpass

>>> set_auth_token(base_url=getpass.getpass("base_url : "),
...                auth_mech="OAuth")

Authentication token is generated and set for the session.

Example 7: Set the Authentication Token by Specifying base_url and auth_mech as "OAuth"

>>> import getpass

>>> set_auth_token(base_url=getpass.getpass("base_url : "),
...                auth_mech="OAuth")

Authentication token is generated, authenticated and set for the session.
True

Example 8: Set the Authentication Token by Specifying "base_url" and "auth_mech" as 'OAuth'

This is valid only for VantageCloud Lake systems where "client_id" can be derived internally from "base_url" and OAuth device code flow is used by default.

>>> import getpass
>>> set_auth_token(base_url=getpass.getpass("base_url : "),
...       auth_url=getpass.getpass("auth_url : "),
...       password=getpass.getpass("password : "),
...       rest_client=getpass.getpass("rest_client : "))

Authentication token is generated and set for the session.
True

Example 8: Set the Authentication Token by Specifying "base_url", "auth_url", "password" and "rest_client" and Generating Keycloak Token Internally

>>> import getpass
>>> set_auth_token(base_url=getpass.getpass("base_url : "),
...       auth_url=getpass.getpass("auth_url : "),
...       password=getpass.getpass("password : "),
...       rest_client=getpass.getpass("rest_client : "))

Authentication token is generated, authenticated and set for the session.
True

Example 9: Set the Authentication Token by Specifying "base_url", "auth_url" "password" and "rest_client" and Generating Keycloak Token Internally

In this example, "auth_mech" is defaulted to 'KEYCLOAK' due to presence of "auth_url" which is only valid for KEYCLOAK IDP.

>>> import getpass
>>> set_auth_token(base_url=getpass.getpass("base_url : "),
...                auth_url=getpass.getpass("auth_url : "),
...                password=getpass.getpass("password : "),
...                rest_client=getpass.getpass("rest_client : "))

Authentication token is generated and set for the session.

Example 10: Set the Authentication Token On a System with KEYCLOAK IDP Using OAuth Password Grant Flow

Specify "base_url", "client_id", "idp_type" as 'KEYCLOAK', "oauth_grant_type" as 'PASSWORD', "idp_username" and "idp_password".

In this example, "auth_mech" is defaulted to 'OAUTH' due to presence of "client_id" and "idp_type" arguments which are valid for OAuth authentication.

>>> import getpass
>>> set_auth_token(base_url=getpass.getpass("base_url : "),
...                client_id=getpass.getpass("client_id : "),
...                idp_type="KEYCLOAK",
...                oauth_grant_type="PASSWORD",
...                idp_username=getpass.getpass("idp_username : "),
...                idp_password=getpass.getpass("idp_password : "),
...                keycloak_realm="teradata")

Authentication token is generated and set for the session.

Example 11: Set the Authentication Token On a System with KEYCLOAK IDP Using OAuth device code flow

Specify "base_url", "client_id", "idp_type" as 'KEYCLOAK' and "oauth_grant_type" as 'DEVICE_CODE'. This will open a browser for authentication.

In this example, "auth_mech" is defaulted to 'OAUTH' due to presence of "client_id" and "idp_type" arguments which are valid for OAuth authentication.

>>> import getpass
>>> set_auth_token(base_url=getpass.getpass("base_url : "),
...                client_id=getpass.getpass("client_id : "),
...                idp_type="KEYCLOAK",
...                oauth_grant_type="DEVICE_CODE",
...                keycloak_realm="teradata")

Opening the browser with URL - https://...
Opened a session in browser. Authenticate yourself in the browser.
Authentication token is generated and set for the session.

Example 12: Set the Authentication Token on a System with PING IDP Using OAuth Device Code Flow

Specify "base_url", "client_id", "idp_type" as 'PING'.

In this example, "auth_mech" is defaulted to 'OAUTH' due to presence of "client_id" and "idp_type" arguments which are valid for OAuth authentication.

>>> import getpass
>>> set_auth_token(base_url=getpass.getpass("base_url : "),
...                client_id=getpass.getpass("client_id : "),
...                idp_type="PING",
...                oauth_grant_type="DEVICE_CODE")

Opening the browser with URL - https://...
Opened a session in browser. Authenticate yourself in the browser.
Authentication token is generated and set for the session.

Example 13: Set the Authentication Token Using OAuth by Explicitly Specifying "oidc_issuer_url"

This example specifies "oidc_issuer_url" to directly provide the OIDC issuer URL instead of deriving it from "idp_type", and uses OAuth device code flow.

>>> import getpass
>>> set_auth_token(base_url=getpass.getpass("base_url : "),
...                client_id=getpass.getpass("client_id : "),
...                oidc_issuer_url=getpass.getpass("oidc_issuer_url : "),
...                oauth_grant_type="DEVICE_CODE")

Opening the browser with URL - https://...
Opened a session in browser. Authenticate yourself in the browser.
Authentication token is generated and set for the session.

Example 14: Set the Authentication Token Using OAuth by Explicitly Specifying "oidc_issuer_url"

This example specifies "oidc_issuer_url" to directly provide the OIDC issuer URL instead of deriving it from "idp_type", and uses OAuth password grant flow.

>>> import getpass
>>> set_auth_token(base_url=getpass.getpass("base_url : "),
...                client_id=getpass.getpass("client_id : "),
...                oidc_issuer_url="https://idp.example.com/sso/realms/teradata",
...                oauth_grant_type="PASSWORD",
...                idp_username=getpass.getpass("idp_username : "),
...                idp_password=getpass.getpass("idp_password : "))

Authentication token is generated and set for the session.

Example 15: Set the Authentication Token Using OAuth with Custom Scope

This example requests additional permissions using "oauth_scope" parameter.

>>> import getpass
>>> set_auth_token(base_url=getpass.getpass("base_url : "),
...                client_id=getpass.getpass("client_id : "),
...                idp_type="KEYCLOAK",
...                oauth_grant_type="PASSWORD",
...                idp_username=getpass.getpass("idp_username : "),
...                idp_password=getpass.getpass("idp_password : "),
...                oauth_scope="openid")

Authentication token is generated and set for the session.

Example 16: Set the Authentication Token and Further Access the Token and Session Details From the auth_manager Object

This example is useful when you want to manage the token and session details for custom use cases like passing the token in custom headers for other REST services or managing session for vectorestore.

>>> import getpass
>>> auth_manager = set_auth_token(base_url=getpass.getpass("base_url : "),
...                               auth_token=getpass.getpass("auth_token : "))
>>> auth_manager.get_token()

'eyJ0eXAiOiJKV1QiLCJhbGciOi...'