ads.secrets package

Submodules

ads.secrets.adb module

class ads.secrets.adb.ADBSecret(user_name: str, password: str, service_name: str, wallet_location: str | None = None, wallet_file_name: str | None = None, wallet_content: dict | None = None, wallet_secret_ids: list = <factory>)[source]

Bases: Secret

Dataclass representing the attributes managed and serialized by ADBSecretKeeper

password: str
service_name: str
user_name: str
wallet_content: dict = None
wallet_file_name: str = None
wallet_location: str = None
wallet_secret_ids: list
class ads.secrets.adb.ADBSecretKeeper(user_name: str | None = None, password: str | None = None, service_name: str | None = None, wallet_location: str | None = None, wallet_dir: str | None = None, repository_path: str | None = None, repository_key: str | None = None, **kwargs)[source]

Bases: SecretKeeper

ADBSecretKeeper provides an interface to save ADW/ATP database credentials. This interface does not store the wallet file by default. For saving wallet file, set save_wallet=True while calling ADBSecretKeeper.save method.

Examples

>>> # Saving credentials without saving the wallet file
>>> from ads.secrets.adw import ADBSecretKeeper
>>> vault_id = "ocid1.vault.oc1..<unique_ID>"
>>> key_id = "ocid1.key..<unique_ID>"

>>> import ads
>>> ads.set_auth("resource_principal") # If using resource principal for authentication
>>> connection_parameters={
...     "user_name":"admin",
...     "password":"<your password>",
...     "service_name":"service_name_{high|low|med}",
...     "wallet_location":"/home/datascience/Wallet_xxxx.zip"
... }
>>> adw_keeper = ADBSecretKeeper(vault_id=vault_id, key_id=key_id, **connection_parameters)
>>> adw_keeper.save("adw_employee", "My DB credentials", freeform_tags={"schema":"emp"}) # Does not save the wallet file
>>> print(adw_keeper.secret_id) # Prints the secret_id of the stored credentials
>>> adw_keeper.export_vault_details("adw_employee_att.json", format="json") # Save the secret id and vault info to a json file

>>> # Loading credentails
>>> import ads
>>> ads.set_auth("resource_principal") # If using resource principal for authentication
>>> from ads.secrets.adw import ADBSecretKeeper
>>> secret_id = "ocid1.vaultsecret.oc1..<unique_ID>"
>>> with ADBSecretKeeper.load_secret(source=secret_id,
                             wallet_location='/home/datascience/Wallet_xxxxxx.zip') as adw_creds:
...     import pandas as pd
...     df = pd.DataFrame.ads.read_sql("select * from EMPLOYEE", connection_parameters=adw_creds)

>>> myadw_creds = ADBSecretKeeper.load_secret(source='adw_employee_att.json', format="json"
...                          wallet_location='/home/datascience/Wallet_xxxxxx.zip')
>>> pd.DataFrame.ads.read_sql("select * from ATTRITION_DATA", connection_parameters=myadw_creds.to_dict()).head(2)

>>> # Saving and loading credentials with wallet storage
>>> # Saving credentials
>>> from ads.secrets.adw import ADBSecretKeeper
>>> vault_id = "ocid1.vault.oc1..<unique_ID>"
>>> key_id = "ocid1.key.oc1..<unique_ID>"

>>> import ads
>>> ads.set_auth("resource_principal") # If using resource principal for authentication
>>> connection_parameters={
...     "user_name":"admin",
...     "password":"<your password>",
...     "service_name":"service_name_{high|low|med}",
...     "wallet_location":"/home/datascience/Wallet_xxxx.zip"
... }
>>> adw_keeper = ADBSecretKeeper(vault_id=vault_id, key_id=key_id, **connection_parameters)
>>> adw_keeper.save("adw_employee", "My DB credentials", freeform_tags={"schema":"emp"}, save_wallet=True)
>>> print(adw_keeper.secret_id) # Prints the secret_id of the stored credentials
>>> adw_keeper.export_vault_details("adw_employee_att.json") # Save the secret id and vault info to a json file

>>> # Loading credentails
>>> import ads
>>> ads.set_auth("resource_principal") # If using resource principal for authentication
>>> from ads.secrets.adw import ADBSecretKeeper
>>> secret_id = "ocid1.vaultsecret.oc1..<unique_ID>"
>>> with ADBSecretKeeper.load_secret(source=secret_id) as adw_creds:
...     import pandas as pd
...     df = pd.DataFrame.ads.read_sql("select * from EMPLOYEE", connection_parameters=adw_creds)

>>> myadw_creds = ADBSecretKeeper.load_secret(source='adw_employee_att.json', format='json')
>>> pd.DataFrame.ads.read_sql("select * from ATTRITION_DATA", connection_parameters=myadw_creds.to_dict()).head(2)
Parameters:

  • user_name ((str, optioanl). Default None) – user_name of the databse

  • password ((str, optional). Default None) – password for connecting to the database

  • service_name ((str, optional). Default None) – service name of the ADB instance

  • wallet_location ((str, optional). Default None) – full path to the wallet zip file used for connecting to ADB instance.

  • wallet_dir ((str, optional). Default None) – local directory where the extracted wallet content is saved

  • repository_path ((str, optional). Default None.) – Path to credentials repository. For more details refer ads.database.connection

  • repository_key ((str, optional). Default None.) – Configuration key for loading the right configuration from repository. For more details refer ads.database.connection

  • kwargs – vault_id: str. OCID of the vault where the secret is stored. Required for saving secret. key_id: str. OCID of the key used for encrypting the secret. Required for saving secret. compartment_id: str. OCID of the compartment where the vault is located. Required for saving secret. auth: dict. Dictionay returned from ads.common.auth.api_keys() or ads.common.auth.resource_principal(). By default, will follow what is set in ads.set_auth. Use this attribute to override the default.

decode() → ADBSecretKeeper[source]

Converts the content in self.secret to ADBSecret and stores in self.data

If the wallet_location is passed through the constructor, then retain it. We do not want to override what user has passed in If the wallet_location was not passed, but the sercret has wallet_secret_ids, then we generate the wallet zip file in the location specified by wallet_dir in the constructor

Returns:

Returns self object

Return type:

ADBSecretKeeper

encode(serialize_wallet: bool = False) → ADBSecretKeeper[source]

Prepares content to save in vault. The user_name, password and service_name and the individual files inside the wallet zip file are base64 encoded and stored in self.secret

Parameters:

serialize_wallet (bool, optional) – When set to True, loads the wallet zip file and encodes the content of each file in the zip file.

Returns:

Returns self object

Return type:

ADBSecretKeeper

save(name: str, description: str, freeform_tags: dict | None = None, defined_tags: dict | None = None, save_wallet: bool = False) → ADBSecretKeeper[source]

Saves credentials to Vault and returns self.

Parameters:

  • name (str) – Name of the secret when saved in the Vault.

  • description (str) – Description of the secret when saved in the Vault.

  • freeform_tags ((dict, optional). Default is None) – freeform_tags to be used for saving the secret in OCI console.

  • defined_tags ((dict, optional). Default is None) – Save the tags under predefined tags in OCI console.

  • save_wallet ((bool, optional). Default is False) – If set to True, saves the contents of the wallet file as separate secret.

Returns:

Returns self object

Return type:

ADBSecretKeeper

ads.secrets.auth_token module

class ads.secrets.auth_token.AuthToken(auth_token: str)[source]

Bases: Secret

AuthToken dataclass holds auth_token attribute

auth_token: str
class ads.secrets.auth_token.AuthTokenSecretKeeper(auth_token=None, **kwargs)[source]

Bases: SecretKeeper

AuthTokenSecretKeeper uses ads.secrets.auth_token.AuthToken class to manage Auth Token credentials. The credentials are stored in Vault as a dictionary with the following format - {“auth_token”:”user provided value”}

Examples

>>> from ads.secrets.auth_token import AuthTokenSecretKeeper
>>> import ads
>>> ads.set_auth("resource_principal") #If using resource principal for authentication
>>> # Save Auth Tokens or Acess Keys to the vault
>>>
>>>
>>> authtoken2 = AuthTokenSecretKeeper(vault_id=vault_id,
...            key_id=key_id,
...            auth_token="<your auth token>").save("my_xyz_auth_token2",
...                                                                 "This is my auth token for git repo xyz",
...                                                                 freeform_tags={"gitrepo":"xyz"})
>>> authtoken2.export_vault_details("my_git_token_vault_info.yaml", format="yaml")
>>> # Loading credentials
>>> with AuthTokenSecretKeeper.load_secret(source="ocid1.vaultsecret.oc1..<unique_ID>",
...                                export_prefix="mygitrepo",
...                                export_env=True
...                               ) as authtoken:
...     import os
...     print("Credentials inside environment variable:", os.environ.get('mygitrepo.auth_token'))
...     print("Credentials inside `authtoken` object: ", authtoken)
Credentials inside environment variable: <your auth token>
Credentials inside `authtoken` object:  {'auth_token': '<your auth token>'}
>>> print("Credentials inside `authtoken` object: ", authtoken)
Credentials inside `authtoken` object:  {'auth_token': None}
>>> print("Credentials inside environment variable:", os.environ.get('mygitrepo.auth_token'))
Credentials inside environment variable: None
Parameters:

  • auth_token ((str, optional). Default None) – auth token string that needs to be stored in the vault

  • kwargs – vault_id: str. OCID of the vault where the secret is stored. Required for saving secret. key_id: str. OCID of the key used for encrypting the secret. Required for saving secret. compartment_id: str. OCID of the compartment where the vault is located. Required for saving secret. auth: dict. Dictionay returned from ads.common.auth.api_keys() or ads.common.auth.resource_principal(). By default, will follow what is set in ads.set_auth. Use this attribute to override the default.

decode() → AuthTokenSecretKeeper[source]

Converts the content in self.encoded to AuthToken and stores in self.data

Returns:

Returns the self object after decoding self.encoded and updates self.data

Return type:

AuthTokenSecretKeeper

ads.secrets.big_data_service module

class ads.secrets.big_data_service.BDSSecret(principal: str, hdfs_host: str, hive_host: str, hdfs_port: str, hive_port: str, kerb5_path: str | None = None, kerb5_content: dict | None = None, keytab_path: str | None = None, keytab_content: dict | None = None, secret_id: str = <factory>)[source]

Bases: Secret

Dataclass representing the attributes managed and serialized by BDSSecretKeeper.

principal

The unique identity to which Kerberos can assign tickets.

Type:

str

hdfs_host

hdfs host name from the bds cluster.

Type:

str

hive_host

hive host name from the bds cluster.

Type:

str

hdfs_port

hdfs port from the bds cluster.

Type:

str

hive_port

hive port from the bds cluster.

Type:

str

kerb5_path

krb5.conf file path.

Type:

str

kerb5_content

Content of the krb5.conf.

Type:

dict

keytab_path

Path to the keytab file.

Type:

str

keytab_content

Content of the keytab file.

Type:

dict

secret_id

secret id where the BDSSecret is stored.

Type:

str

hdfs_host: str
hdfs_port: str
hive_host: str
hive_port: str
kerb5_content: dict = None
kerb5_path: str = None
keytab_content: dict = None
keytab_path: str = None
principal: str
secret_id: str
class ads.secrets.big_data_service.BDSSecretKeeper(principal: str | None = None, hdfs_host: str | None = None, hive_host: str | None = None, hdfs_port: str | None = None, hive_port: str | None = None, kerb5_path: str | None = None, kerb5_content: str | None = None, keytab_path: str | None = None, keytab_content: str | None = None, keytab_dir: str | None = None, secret_id: str | None = None, **kwargs)[source]

Bases: SecretKeeper

BDSSecretKeeper provides an interface to save BDS hdfs and hive credentials. This interface does not store the wallet file by default. For saving keytab and krb5.cofig file, set save_files=True while calling BDSSecretKeeper.save method.

principal

The unique identity to which Kerberos can assign tickets.

Type:

str

hdfs_host

hdfs host name from the bds cluster.

Type:

str

hive_host

hive host name from the bds cluster.

Type:

str

hdfs_port

hdfs port from the bds cluster.

Type:

str

hive_port

hive port from the bds cluster.

Type:

str

kerb5_path

krb5.conf file path.

Type:

str

kerb5_content

Content of the krb5.conf.

Type:

dict

keytab_path

Path to the keytab file.

Type:

str

keytab_content

Content of the keytab file.

Type:

dict

secret_id

secret id where the BDSSecret is stored.

Type:

str

kwargs
------
vault_id
Type:

str. OCID of the vault where the secret is stored. Required for saving secret.

key_id
Type:

str. OCID of the key used for encrypting the secret. Required for saving secret.

compartment_id
Type:

str. OCID of the compartment where the vault is located. Required for saving secret.

auth
Type:

dict. Dictionay returned from ads.common.auth.api_keys() or ads.common.auth.resource_principal(). By default, will follow what is set in ads.set_auth. Use this attribute to override the default.

Parameters:

  • principal (str) – The unique identity to which Kerberos can assign tickets.

  • hdfs_host (str) – hdfs host name from the bds cluster.

  • hive_host (str) – hive host name from the bds cluster.

  • hdfs_port (str) – hdfs port from the bds cluster.

  • hive_port (str) – hive port from the bds cluster.

  • kerb5_path (str) – krb5.conf file path.

  • kerb5_content (dict) – Content of the krb5.conf.

  • keytab_path (str) – Path to the keytab file.

  • keytab_content (dict) – Content of the keytab file.

  • keytab_dir ((str, optional).) – Default None. Local directory where the extracted keytab content is saved.

  • secret_id (str) – secret id where the BDSSecret is stored.

kwargs

vault_id: str. OCID of the vault where the secret is stored. Required for saving secret. key_id: str. OCID of the key used for encrypting the secret. Required for saving secret. compartment_id: str. OCID of the compartment where the vault is located. Required for saving secret. auth: dict. Dictionay returned from ads.common.auth.api_keys() or ads.common.auth.resource_principal(). By default, will follow what is set in ads.set_auth. Use this attribute to override the default.

decode(save_files: bool = True) → ads.secrets.bds.BDSSecretKeeper[source]

Converts the content in self.secret to BDSSecret and stores in self.data

If the keytab_path and kerb5_path are passed through the constructor, then retain it. We do not want to override what user has passed in If the keytab_path and kerb5_path are not passed, but the sercret has secret_id, then we generate the keytab file in the location specified by keytab_path in the constructor.

Returns:

Returns self object

Return type:

BDSSecretKeeper

encode(serialize: bool = True) → ads.secrets.bds.BDSSecretKeeper[source]

Prepares content to save in vault. The port, host name and the keytab and krb5.config files are base64 encoded and stored in self.secret

Parameters:

serialize (bool, optional) – When set to True, loads the keytab and krb5.config file and encodes the content of both files.

Returns:

Returns self object

Return type:

BDSSecretKeeper

save(name: str, description: str, freeform_tags: dict = None, defined_tags: dict = None, save_files: bool = True) → ads.secrets.bds.BDSSecretKeeper[source]

Saves credentials to Vault and returns self.

Parameters:

  • name (str) – Name of the secret when saved in the Vault.

  • description (str) – Description of the secret when saved in the Vault.

  • freeform_tags ((dict, optional). Default is None) – freeform_tags to be used for saving the secret in OCI console.

  • defined_tags ((dict, optional). Default is None) – Save the tags under predefined tags in OCI console.

  • save_files ((bool, optional). Default is False) – If set to True, saves the contents of the keytab and krb5 file as separate secret.

Returns:

Returns self object

Return type:

BDSSecretKeeper

ads.secrets.mysqldb module

class ads.secrets.mysqldb.MySQLDBSecret(user_name: str, password: str, host: str, port: str, database: str | None = None)[source]

Bases: Secret

Dataclass representing the attributes managed and serialized by MySQLDBSecretKeeper

database: str = None
host: str
password: str
port: str
user_name: str
class ads.secrets.mysqldb.MySQLDBSecretKeeper(user_name: str | None = None, password: str | None = None, host: str | None = None, port: str = '3306', database: str | None = None, repository_path: str | None = None, repository_key: str | None = None, **kwargs)[source]

Bases: SecretKeeper

MySQLDBSecretKeeper provides an interface to save MySQL database credentials. If you use Wallet file for connnecting to the database, please use ADBSecretKeeper.

Examples

>>> from ads.secrets.mysqldb import MySQLDBSecretKeeper
>>> vault_id = "ocid1.vault.oc1..<unique_ID>"
>>> key_id = "ocid1.key..<unique_ID>"

>>> import ads
>>> ads.set_auth("resource_principal") # If using resource principal for authentication
>>> connection_parameters={
...     "user_name":"<your user name>",
...     "password":"<your password>",
...     "host":"<db host>",
...     "port":"<db port>",
...     "database":"<database>",
... }
>>> mysqldb_keeper = MySQLDBSecretKeeper(vault_id=vault_id, key_id=key_id, **connection_parameters)
>>> mysqldb_keeper.save("mysqldb_employee", "My DB credentials", freeform_tags={"schema":"emp"})
>>> print(mysqldb_keeper.secret_id) # Prints the secret_id of the stored credentials
>>> mysqldb_keeper.export_vault_details("mysqldb_employee_att.json") # Save the secret id and vault info to a json file

>>> # Loading credentails
>>> import ads
>>> ads.set_auth("resource_principal") # If using resource principal for authentication
>>> from ads.secrets.mysqldb import MySQLDBSecretKeeper
>>> secret_id = "ocid1.vaultsecret.oc1..<unique_ID>"
>>> with MySQLDBSecretKeeper.load_secret(source=secret_id) as mysqldb_creds:
...     import pandas as pd
...     df = pd.DataFrame.ads.read_sql("select * from EMPLOYEE", connection_parameters=mysqldb_creds, engine="mysql")

>>> mymysqldb_creds = MySQLDBSecretKeeper.load_secret(source='mysqldb_employee_att.json', format="json")
>>> pd.DataFrame.ads.read_sql("select * from ATTRITION_DATA", connection_parameters=mymysqldb_creds.to_dict(), engine="mysql").head(2)
Parameters:

  • user_name ((str, optional). Default None) – user_name of the database

  • password ((str, optional). Default None) – password for connecting to the database

  • host ((str, optional). Default None) – Database host name

  • port ((str, optional). Default 1521) – Port number

  • database ((str, optional). Default None) – database name

  • repository_path ((str, optional). Default None.) – Path to credentials repository. For more details refer ads.database.connection

  • repository_key ((str, optional). Default None.) – Configuration key for loading the right configuration from repository. For more details refer ads.database.connection

  • kwargs – vault_id: str. OCID of the vault where the secret is stored. Required for saving secret. key_id: str. OCID of the key used for encrypting the secret. Required for saving secret. compartment_id: str. OCID of the compartment where the vault is located. Required for saving secret. auth: dict. Dictionay returned from ads.common.auth.api_keys() or ads.common.auth.resource_principal(). By default, will follow what is set in ads.set_auth. Use this attribute to override the default.

decode() → MySQLDBSecretKeeper[source]

Converts the content in self.encoded to MySQLDBSecret and stores in self.data

Returns:

Returns self object

Return type:

MySQLDBSecretKeeper

ads.secrets.oracledb module

class ads.secrets.oracledb.OracleDBSecret(user_name: str, password: str, host: str, port: str, service_name: str | None = None, sid: str | None = None, dsn: str | None = None)[source]

Bases: Secret

Dataclass representing the attributes managed and serialized by OracleDBSecretKeeper

dsn: str = None
host: str
password: str
port: str
service_name: str = None
sid: str = None
user_name: str
class ads.secrets.oracledb.OracleDBSecretKeeper(user_name: str | None = None, password: str | None = None, service_name: str | None = None, sid: str | None = None, host: str | None = None, port: str = '1521', dsn: str | None = None, repository_path: str | None = None, repository_key: str | None = None, **kwargs)[source]

Bases: SecretKeeper

OracleDBSecretKeeper provides an interface to save Oracle database credentials. If you use Wallet file for connnecting to the database, please use ADBSecretKeeper.

Examples

>>> from ads.secrets.oracledb import OracleDBSecretKeeper
>>> vault_id = "ocid1.vault.oc1..<unique_ID>"
>>> key_id = "ocid1.key..<unique_ID>"

>>> import ads
>>> ads.set_auth("resource_principal") # If using resource principal for authentication
>>> connection_parameters={
...     "user_name":"<your user name>",
...     "password":"<your password>",
...     "service_name":"service_name",
...     "host":"<db host>",
...     "port":"<db port>",
... }
>>> oracledb_keeper = OracleDBSecretKeeper(vault_id=vault_id, key_id=key_id, **connection_parameters)
>>> oracledb_keeper.save("oracledb_employee", "My DB credentials", freeform_tags={"schema":"emp"})
>>> print(oracledb_keeper.secret_id) # Prints the secret_id of the stored credentials
>>> oracledb_keeper.export_vault_details("oracledb_employee_att.json") # Save the secret id and vault info to a json file

>>> # Loading credentails
>>> import ads
>>> ads.set_auth("resource_principal") # If using resource principal for authentication
>>> from ads.secrets.oracledb import OracleDBSecretKeeper
>>> secret_id = "ocid1.vaultsecret.oc1..<unique_ID>"
>>> with OracleDBSecretKeeper.load_secret(source=secret_id) as oracledb_creds:
...     import pandas as pd
...     df = pd.DataFrame.ads.read_sql("select * from EMPLOYEE", connection_parameters=oracledb_creds)

>>> myoracledb_creds = OracleDBSecretKeeper.load_secret(source='oracledb_employee_att.json', format="json")
>>> pd.DataFrame.ads.read_sql("select * from ATTRITION_DATA", connection_parameters=myoracledb_creds.to_dict()).head(2)
Parameters:

  • user_name ((str, optional). Default None) – user_name of the database

  • password ((str, optional). Default None) – password for connecting to the database

  • service_name ((str, optional). Default None) – service name of the Oracle DB instance

  • sid ((str, optional). Default None) – Provide sid if service name is not available.

  • host ((str, optional). Default None) – Database host name

  • port ((str, optional). Default 1521) – Port number

  • dsn ((str, optional). Default None) – dsn string for connecting with oracledb. Refer cx_Oracle documentation

  • repository_path ((str, optional). Default None.) – Path to credentials repository. For more details refer ads.database.connection

  • repository_key ((str, optional). Default None.) – Configuration key for loading the right configuration from repository. For more details refer ads.database.connection

  • kwargs – vault_id: str. OCID of the vault where the secret is stored. Required for saving secret. key_id: str. OCID of the key used for encrypting the secret. Required for saving secret. compartment_id: str. OCID of the compartment where the vault is located. Required for saving secret. auth: dict. Dictionay returned from ads.common.auth.api_keys() or ads.common.auth.resource_principal(). By default, will follow what is set in ads.set_auth. Use this attribute to override the default.

decode() → OracleDBSecretKeeper[source]

Converts the content in self.encoded to OracleDBSecret and stores in self.data

Returns:

Returns self object

Return type:

OracleDBSecretKeeper

ads.secrets.secrets module

class ads.secrets.secrets.Secret[source]

Bases: object

Base class

serialize(self) → dict[source]

Serializes attributes as dictionary. Returns dictionary with the keys that are serializable.

to_dict(self) → dict[source]

returns dictionarry with the keys that has repr set to True and the value is not None or empty

export_dict -> dict

returns dictionary with the keys that has repr set tp True

export_options -> dcit

returns list of attributes with the fields that has repr set to True

export_dict() → dict[source]

Serializes attributes as dictionary.

Returns:

returns dictionary of key/value pair where the value of the attribute is not None and the field does not have repr`=`False

Return type:

dict

export_options() → list[source]

Returns list of attributes that have repr=True.

Returns:

returns list of fields that does not have repr=False

Return type:

list

serialize() → dict[source]

Serializes attributes as dictionary. An attribute can be marked as not serializable by using metadata field of the field constructor provided by the dataclasses module.

Returns:

returns dictionay of key/value pair where the value of the attribute is not None and not empty and the field does not have metadata = {“serializable”:False}. Refer dataclass python documentation for more details about metadata

Return type:

dict

to_dict() → dict[source]

Serializes attributes as dictionary. Returns only non empty attributes.

Returns:

returns dictionary of key/value pair where the value of the attribute is not None or empty

Return type:

dict

class ads.secrets.secrets.SecretKeeper(content: bytes | None = None, encoded: str | None = None, secret_id: str | None = None, export_prefix: str = '', export_env: bool = False, **kwargs)[source]

Bases: Vault, ContextDecorator

SecretKeeper defines APIs required to serialize and deserialize secrets. Services such as Database, Streaming, and Git require users to provide credentials. These credentials need to be safely accessed at runtime. OCI Vault provides a mechanism for safe storage and access. SecretKeeper uses OCI Vault as a backend to store and retrieve the credentials.

The exact data structure of the credentials varies from service to service.

Parameters:

  • vault_id ((str, optional). Default None) – ocid of the vault

  • key_id ((str, optional). Default None) – ocid of the key that is used for encrypting the content

  • compartment_id ((str, optional). Default None) – ocid of the compartment_id where the vault resides. When available in environment variable - NB_SESSION_COMPARTMENT_OCID, will defult to that.

  • secret_client_auth ((dict, optional, deprecated since 2.5.1). Default None.) – deprecated since 2.5.1. Use auth instead

  • vault_client_auth ((dict, optional, deprecated since 2.5.1). Default None.) – deprecated since 2.5.1. Use auth instead

  • auth ((dict, optional)) – Dictionay returned from ads.common.auth.api_keys() or ads.common.auth.resource_principal(). By default, will follow what is set in ads.set_auth. Use this attribute to override the default.

decode() → SecretKeeper[source]

Decodes the content in self.encoded and sets the vaule in self.secret.

encode()[source]

Stores the secret in self.secret by calling serialize method on self.data. Stores base64 encoded string of self.secret in self.encoded.

export_vault_details(filepath: str, format: str = 'json', storage_options: dict | None = None)[source]

Save secret_id in a json file

Parameters:

  • filepath (str) – Filepath to save the file.

  • format (str) –

    Default is json. Valid values:

    • yaml or yml - to store vault details in a yaml file

    • json - to store vault details in a json file

  • storage_options (dict, optional.) – storage_options dict as required by fsspec library

Returns:

Returns None

Return type:

None

classmethod load_secret(source: str, format: str = 'ocid', export_env: bool = False, export_prefix: str = '', auth=None, storage_options: dict | None = None, **kwargs) → dict | SecretKeeper[source]

Loads secret from vault using secret_id.

Parameters:

  • source (str) –

    Source could be one of the following:

    • OCID of the secret that has the secret content.

    • file path that is json or yaml format with the key - secret_id: ocid1.vaultsecret..<unique_ID>

  • format (str) –

    Defult is ocid. When ocid, the source must be a secret id Value values:

    • ocid - source is expected to be ocid of the secret

    • yaml or yml - source is expected to be a path to a valid yaml file

    • json - source is expected to be a path to a valid json file

  • export_env (str, Default False) – When set to true, the credentails will be exported to the environment variable. When load_secret is invoked using with statement, information exported as environment variable is unset before leaving the with scope

  • export_prefix (str, Default "") – Prefix to the environment variable that is exported.

  • auth (dict, optional) – By default authentication will follow what is configured using ads.set_auth API. Accepts dict returned from ads.common.auth.api_keys() or ads.common.auth.resource_principal().

  • storage_options (dict, optional) – storage_options dict as required by fsspec library

  • kwargs – key word arguments accepted by the constructor of the class from which this method is invoked.

Returns:

  • dict – When called from within with block, Returns a dictionary containing the secret

  • ads.secrets.SecretKeeper – When called without using with operator.

Examples

>>> from ads.secrets import APIKeySecretKeeper
>>> with APIKeySecretKeeper.load_secret(source="ocid1.vaultsecret.**<unique_ID>**",
...                         export_prefix="mykafka",
...                         export_env=True
...                        ) as apisecret:
...     import os
...     print("Credentials inside environment variable:",
...             os.environ.get('mykafka.api_key'))
...     print("Credentials inside `apisecret` object: ", apisecret)
Credentials inside environment variable: <your api key>
Credentials inside `apisecret` object:  {'api_key': 'your api key'}

>>> from ads.secrets import ADBSecretKeeper
>>> with ADBSecretKeeper.load_secret("ocid1.vaultsecret.**<unique_ID>**") as adw_creds2:
...     import pandas as pd
...     df2 = pd.DataFrame.ads.read_sql("select * from ATTRITION_DATA",
...                 connection_parameters=adw_creds2)
...     print(df2.head(2))
            JOBFUNCTION ATTRITION
0  Product Management        No
1  Software Developer        No
required_keys = ['secret_id']
save(name: str, description: str, freeform_tags: dict | None = None, defined_tags: dict | None = None) → SecretKeeper[source]

Saves credentials to Vault and returns self.

Parameters:

  • name (str) – Name of the secret when saved in the Vault.

  • description (str) – Description of the secret when saved in the Vault.

  • freeform_tags (dict, optional) – freeform_tags to be used for saving the secret in OCI console.

  • defined_tags (dict, optional.) – Save the tags under predefined tags in OCI console.

Returns:

Returns self object.

Return type:

SecretKeeper

to_dict() → dict[source]

Returns dict of credentials retrieved from the vault or set through constructor arguments.

Returns:

dict of credentials retrieved from the vault or set through constructor.

Return type:

dict

Module contents