| |
Methods defined here:
- __init__(self, base_url=None, client_id=None, pat_token=None, pem_file=None, **kwargs)
- DESCRIPTION:
Manages the authentication token required to access services running on
Teradata Vantage. Supports PAT/JWT authentication, Basic authentication,
and multiple OAuth 2.0 flows provided by multiple Identity Providers (Keycloak, Ping Federate).
Notes:
* User must have a privilege to login with a NULL password to use set_auth_token.
Refer to GRANT LOGON section in Teradata Documentation for more details.
* When "auth_mech" is not specified, arguments are used in the following combination
to derive authentication mechanism.
* If "base_url" and "client_id" are specified then token generation is done through OAuth on VCL platform.
* If "base_url", "pat_token", "pem_file" are specified then token generation is done using PAT.
* If "base_url", "username" and "password" are specified authentication token can be generated
via two mechanisms viz. basic authentication or OAuth password grant. In such cases,
if "auth_mech" is not explicitly provided, then basic authentication is given the priority.
* If "base_url" and "auth_token" are specified then readily available token is used.
* If only "base_url" is specified then token generation is done through OAuth device flow and
client id will be extracted internally from "base_url" considering system is VCL based.
* Refresh token works for 'OAUTH' and 'KEYCLOAK' authentication mechanisms which are variants of
OAuth 2.0. authentication flows.
* Use the argument "kid" 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".
* Refer to below table to choose the right combination of arguments for different
authentication mechanisms and flows.
Legend: [...] = Optional, DC = DEVICE_CODE, PW = PASSWORD grant
Notes:
* DC (DEVICE_CODE) opens browser for authentication.
* PW (PASSWORD) requires idp_username and idp_password for direct login.
+-------------+------------+-------------+------------------------------------+
| Infra | IDP | auth_mech | Required Args and [Optional Args] |
+=============+============+=============+====================================+
| ANY | - | JWT | base_url, auth_token |
+=============+============+=============+====================================+
| ANY | - | BASIC | base_url, username, password |
+=============+============+=============+====================================+
| VCL | - | PAT | base_url, pat_token, pem_file |
| | | | [username, kid, expiration_time, |
| | | | validate_jwt, valid_from] |
+=============+============+=============+====================================+
| VCL | VCL_IN_ | OAUTH (DC) | base_url, client_id |
| | HOUSE | | (username is required but can be |
| | | | auto-derived from connection) |
| | | | [oauth_scope] |
+-------------+------------+-------------+------------------------------------+
| | VCL_IN_ | OAUTH (DC) | base_url (client_id auto-derived |
| | HOUSE | auto-derive | from base_url) |
| | | | [oauth_scope] |
+=============+============+=============+=====================================+
| On-Prem | KEYCLOAK | OAUTH (DC) | base_url, client_id, |
| | | | idp_type='KEYCLOAK' |
| | | | [oidc_issuer_url, oauth_scope, |
| | | | keycloak_realm] |
+-------------+------------+-------------+------------------------------------|
| | KEYCLOAK | OAUTH (PW) | base_url, client_id, |
| | | | idp_type='KEYCLOAK', |
| | | | idp_username, idp_password |
| | | | [oidc_issuer_url, oauth_scope, |
| | | | keycloak_realm] |
+-------------+------------+-------------+------------------------------------+
| | KEYCLOAK | KEYCLOAK | base_url, auth_url, password |
| | | (legacy PW) | [rest_client, username] |
| | | | (idp_username and idp_password are |
| | | | required and derived from username|
| | | | and password) |
| | | | Note: Use OAUTH instead |
+=============+============+=============+====================================+
| VCE | PING | OAUTH (DC) | base_url, client_id, |
| | | | idp_type='PING', |
| | | | [oidc_issuer_url, oauth_scope] |
+=============+============+=============+====================================+
| Any | OAuth 2.0 | OAUTH (DC) | base_url, client_id, |
| | IDP | | oidc_issuer_url |
| | | | [oauth_scope] |
+-------------+------------+-------------+------------------------------------+
| Any | OAuth 2.0 | OAUTH (PW) | base_url, client_id, |
| | IDP | | oidc_issuer_url, |
| | | | idp_username, idp_password |
| | | | [oauth_scope] |
+-------------+------------+-------------+------------------------------------+
PARAMETERS:
base_url:
Required Argument.
Specifies the endpoint URL for a given environment on Teradata Vantage system.
Types: str
client_id:
Optional Argument.
Specifies the id of the application that requests the access token from
Vantage Cloud Lake(VCL) or other OAuth based identity providers(IDPs).
Notes:
* teradataml recommends to explicitly provide this argument to avoid ambiguity.
* If not specified with OAuth flows, it will be derived from "base_url" in case of VCL systems.
* Required for OAuth based authentication with explicit IDP configuration.
Types: str
pat_token:
Required, if PAT authentication is to be used, optional otherwise.
Specifies the PAT token generated from Vantage Cloud Lake Console.
Types: str
pem_file:
Required, if PAT authentication is to be used, optional otherwise.
Specifies the path to private key file which is generated from Vantage Cloud Lake Console.
Note:
Teradata recommends not to change the name of the file generated from Vantage Cloud Lake
Console. If the name of the file is changed, then authentication token generated from
this class will not work.
Types: str
**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.
Notes:
* Use this option only if name of the database username has lowercase letters.
* Required for OAuth password grant and Basic authentication flows.
Types: str
password:
Optional Argument.
Specifies the password for database user.
Notes:
* Required for Basic authentication mechanism.
* Required for OAuth password grant flow.
* Required for Keycloak authentication.
Types: str
expiration_time:
Optional Argument.
Specifies the expiration time of the token in seconds. After expiry time, JWT
token expires and UserEnv methods does not work, user should regenerate the token.
Note:
* This option is used only for PAT and not for OAuth.
Default Value: 31536000
Types: int
auth_token:
Optional Argument.
Specifies the authentication token required to access services running
on Teradata Vantage.
Note:
* Use this option only if user has got JWT token and wants to set
the same instead of generating it again.
Types: str
kid:
Optional Argument.
Specifies the name of the key which is used while generating "pem_file".
Note:
* 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".
Types: str
auth_url:
Optional Argument.
Specifies the token endpoint URL for a keycloak server.
Types: str
rest_client:
Optional Argument.
Specifies the client-id registered at keycloak IDP for given teradata site.
Notes:
* teradataml recommends to use "client_id" argument along
with "auth_mech" as 'OAUTH' and "idp_type" as 'KEYCLOAK'
for keycloak IDP paired with "oauth_grant_type".
* This argument is kept for backward compatibility,
when "auth_mech" is 'KEYCLOAK'.
Permitted values: "VECTORSTORE"
Default value: "VECTORSTORE"
Types: str
auth_mech:
Optional Argument.
Specifies the mechanism to be used for generating authentication token.
Notes:
* teradataml recommends to explicitly provide this argument to avoid ambiguity
in authentication mechanism derivation.
* 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") using client id which can be specified by
user in "client_id" argument or can be derived internally from "base_url"
in case of VCL systems.
* 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. teradataml recommends to use
"auth_mech" as 'OAUTH' with "idp_type" as 'KEYCLOAK' instead of using
'KEYCLOAK' as value for "auth_mech" argument when keycloak IDP is used.
Permitted Values: "OAUTH", "PAT", "BASIC", "JWT", "KEYCLOAK".
Types: str
validate_jwt:
Optional Argument.
Specifies whether to validate generated JWT token or not.
Note:
* Applicable only when "auth_mech" is 'PAT'.
Default value: True
Types: boolean
valid_from:
Optional Argument.
Specifies epoch seconds representing time from which JWT token will be valid.
Note:
* Applicable only when "auth_mech" is 'PAT'.
Default value: 0
Types: int
oauth_grant_type:
Optional Argument.
Specifies the OAuth 2.0 grant type to use for authentication.
Notes:
* 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"
Types: str
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.
Notes:
* teradataml 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"
Types: str
oidc_issuer_url:
Optional Argument.
Specifies the base URL of the Identity Provider which is further appended
with ".well-known/openid-configuration" for OIDC endpoint discovery in OAuth
flows.
e.g.
1. 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.
2. 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".
3. 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".
Notes:
* If not specified, it will be derived from "base_url" and "idp_type".
Types: str
idp_username:
Optional Argument.
Specifies the IDP username for OAuth password grant flow.
Notes:
* If not specified, defaults to the value of "username" parameter.
* Use this when IDP username differs from database username.
Types: str
idp_password:
Optional Argument.
Specifies the IDP password for OAuth password grant flow.
Notes:
* If not specified, defaults to the value of "password" parameter.
* Use this when IDP password differs from database password.
Types: str
keycloak_realm:
Optional Argument.
Specifies the Keycloak realm name when using Keycloak IDP.
Notes:
* 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"
Types: str
oauth_scope:
Optional Argument.
Specifies the OAuth 2.0 scope(s) 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').
Notes:
* 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"
Types: str
RAISES:
TeradataMlException, RuntimeError.
EXAMPLES:
# Example 1: Set the Authentication token using default client_id.
>>> import getpass
>>> set_auth_token(base_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.
>>> set_auth_token(base_url=getpass.getpass("base_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(base_url=getpass.getpass("base_url : "),
... pat_token=getpass.getpass("pat_token : "),
... pem_file=getpass.getpass("pem_file : "))
Authentication token is generated, authenticated 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(base_url=getpass.getpass("base_url : "),
... pat_token=getpass.getpass("pat_token : "),
... pem_file=getpass.getpass("pem_file : "),
... username=getpass.getpass("username : "))
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 "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 6: Set the authentication token via 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 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_token=getpass.getpass("auth_token : "))
Authentication token is set for the session.
# Example 8: Set the authentication token for by specifying "base_url" and
# "auth_mech" as 'OAuth'. This is valid only for VCL 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_mech="OAuth")
Authentication token is generated and set for the session.
# Example 9: Set the authentication token for 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 system with KEYCLOAK IDP via
# 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 via
# 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 via
# 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 via OAuth by explicitly
# specifying "oidc_issuer_url". This is useful when user
# wants to directly provide the OIDC issuer URL instead of
# deriving it from "idp_type". Here, OAuth device code flow
# is used as an example.
>>> 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 via OAuth by explicitly
# specifying "oidc_issuer_url". This is useful when user
# wants to directly provide the OIDC issuer URL instead of
# deriving it from "idp_type". Here, OAuth password grant
# flow is used as an example.
>>> 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 via OAuth with custom scope.
# Request 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 is
# useful when user wants 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...'
Data descriptors defined here:
- __dict__
- dictionary for instance variables
- __weakref__
- list of weak references to the object
|