Authentication

When you are working within a notebook session, you are operating as the datascience Linux user. This user does not have an OCI Identity and Access Management (IAM) identity, so it has no access to the Oracle Cloud Infrastructure API. Oracle Cloud Infrastructure resources include Data Science projects, models, jobs, model deployment, and the resources of other OCI services, such as Object Storage, Functions, Vault, Data Flow, and so on. To access these resources, you must use one of the two provided authentication approaches:

1. Authenticating Using Resource Principals

Prerequisite

  • You are operating within a OCI service that has resource principal based authentication configured

  • You have setup the required policies allowing the resourcetype within which you are operating to use/manage the target OCI resources.

This is the generally preferred way to authenticate with an OCI service. A resource principal is a feature of IAM that enables resources to be authorized principal actors that can perform actions on service resources. Each resource has its own identity, and it authenticates using the certificates that are added to it. These certificates are automatically created, assigned to resources, and rotated avoiding the need for you to upload credentials to your notebook session.

Data Science enables you to authenticate using your notebook session’s resource principal to access other OCI resources. When compared to using the OCI configuration and key files approach, using resource principals provides a more secure and easy way to authenticate to the OCI APIs.

You can choose to use the resource principal to authenticate while using the Accelerated Data Science (ADS) SDK by running ads.set_auth(auth='resource_principal') in a notebook cell. For example:

import ads
ads.set_auth(auth='resource_principal')
compartment_id = os.environ['NB_SESSION_COMPARTMENT_OCID']
pc = ProjectCatalog(compartment_id=compartment_id)
pc.list_projects()

2. Authenticating Using API Keys

Prerequisite

  • You have setup api keys as per the instruction here

Use API Key setup when you are working from a local workstation or on platform which does not support resource principals.

This is the default method of authentication. You can also authenticate as your own personal IAM user by creating or uploading OCI configuration and API key files inside your notebook session environment. The OCI configuration file contains the necessary credentials to authenticate your user against the model catalog and other OCI services like Object Storage. You can create this file using a setup dialog or manually using a text editor. See Setting up the Configuration File for steps to follow.

Note

If you already have an OCI configuration file (config) and associated keys, you can upload them directly to the /home/datascience/.oci directory using the JupyterLab Upload Files or the drag-and-drop option.

3. Authenticating Using Instance Principals

Prerequisite

  • You are operating within an OCI compute instance

  • You have created a Dynamic Group with Matching Rules to include your compute instances, and you have authored policies allowing this Dynamic Group to perform actions within your tenancy

For more information on Instance Principals, see Calling Services from an Instance.

You can choose to use the instance principal to authenticate while using the Accelerated Data Science (ADS) SDK by running ads.set_auth(auth='instance_principal'). For example:

import ads
ads.set_auth(auth='instance_principal')
mc = ModelCatalog(compartment_id="<compartment_id>")
mc.list_models()

4. Authenticating Using Security Token

Prerequisite

  • You have setup security token as per the instruction here

You can choose to use the security token to authenticate while using the Accelerated Data Science (ADS) SDK by running ads.set_auth(auth='security_token'). For example:

import ads
ads.set_auth(auth='security_token')
mc = ModelCatalog(compartment_id="<compartment_id>")
mc.list_models()

5. Overriding Defaults

The default authentication that is used by ADS is set with the set_auth() method. However, each relevant ADS method has an optional parameter to specify the authentication method to use. The most common use case for this is when you have different permissions in different API keys or there are differences between the permissions granted in the resource principals and your API keys.

By default, ADS uses API keys to sign requests to OCI resources. The set_auth() method is used to explicitly set a default signing method. This method accepts one of four strings "api_key", "resource_principal", instance_principal or security_token.

The ~/.oci/config configuration allow for multiple configurations to be stored in the same file. The set_auth() method takes is oci_config_location parameter that specifies the location of the configuration, and the default is "~/.oci/config". Each configuration is called a profile, and the default profile is DEFAULT. The set_auth() method takes in a parameter profile. It specifies which profile in the ~/.oci/config configuration file to use. In this context, the profile parameter is only used when API keys are being used. If no value for profile is specified, then the DEFAULT profile section is used.

import ads
import oci

ads.set_auth("api_key") # default signer is set to API Keys
ads.set_auth("api_key", profile = "TEST") # default signer is set to API Keys and to use TEST profile
ads.set_auth("api_key", oci_config_location = "~/.test_oci/config") # default signer is set to API Keys and to use non-default oci_config_location
private_key_content = """
-----BEGIN RSA PRIVATE KEY-----
MIIBIjANBgkqhkiG9w0BAQE...
...
-----END RSA PRIVATE KEY-----
"""
config = dict(
  user="ocid1.user.oc1..xxx",
  fingerprint="35:67:25:90:89:87:45:78:bf:4h:g5:13:16:32:4d:f4",
  tenancy="ocid1.tenancy.oc1..xxx",
  region="us-ashburn-1",
  key_content=private_key_content,
)
ads.set_auth(config = config) # default signer is set to API Keys with private key content

ads.set_auth("resource_principal")  # default signer is set to resource principal authentication
ads.set_auth("instance_principal")  # default signer is set to instance principal authentication
ads.set_auth("security_token")  # default signer is set to security token authentication

signer = oci.auth.signers.ResourcePrincipalsFederationSigner()
ads.set_auth(config={}, signer=signer) # default signer is set to ResourcePrincipalsFederationSigner

signer_callable = oci.auth.signers.ResourcePrincipalsFederationSigner
ads.set_auth(signer_callable=signer_callable) #  default signer is set ResourcePrincipalsFederationSigner callable

The auth module has helper functions that return a signer which is used for authentication. The api_keys() method returns a signer that uses the API keys in the .oci configuration directory. There are optional parameters to specify the location of the API keys and the profile section. The resource_principal() method returns a signer that uses resource principals. The method default_signer() returns either a signer for API Keys or resource principals depending on the defaults that have been set. The set_auth() method determines which signer type is the default. If nothing is set then API keys are the default.

Additional signers may be provided by running set_auth() with signer or signer_callable with optional signer_kwargs parameters. You can find the list of additional signers here.

from ads.common import auth as authutil
from ads.common import oci_client as oc

# Example 1: Create Object Storage client with the default signer.
auth = authutil.default_signer()
oc.OCIClientFactory(**auth).object_storage

# Example 2: Create Object Storage client with timeout set to 6000 using resource principal authentication.
auth = authutil.resource_principal({"timeout": 6000})
oc.OCIClientFactory(**auth).object_storage

# Example 3: Create Object Storage client with timeout set to 6000 using API Key authentication.
auth = authutil.api_keys(oci_config="/home/datascience/.oci/config", profile="TEST", client_kwargs={"timeout": 6000})
oc.OCIClientFactory(**auth).object_storage

# Example 4: Create Object Storage client with timeout set to 6000 using security token authentication.
auth = authutil.security_token(oci_config="/home/datascience/.oci/config", profile="test_session", client_kwargs={"timeout": 6000})
oc.OCIClientFactory(**auth).object_storage

In the this example, the default authentication uses API keys specified with the set_auth method. However, since the os_auth is specified to use resource principals, the notebook session uses the resource principal to access OCI Object Store.

set_auth("api_key") # default signer is set to api_key
os_auth = authutil.resource_principal() # use resource principal to as the preferred way to access object store

More signers can be created using the create_signer() method. With the auth_type parameter set to instance_principal, the method will return a signer that uses instance principals. For other signers there are signer, signer_callable or signer_kwargs parameters. Here are examples:

import ads
import oci

# Example 1. Create signer that uses instance principals
auth = ads.auth.create_signer("instance_principal")

# Example 2. Create signer that uses security token
auth = ads.auth.create_signer("security_token", profile="test_session")

# Example 3. Provide a ResourcePrincipalsFederationSigner object
signer = oci.auth.signers.ResourcePrincipalsFederationSigner()
auth = ads.auth.create_signer(config={}, signer=signer)

# Example 4. Create signer that uses instance principals with log requests enabled
signer_callable = oci.auth.signers.InstancePrincipalsSecurityTokenSigner
signer_kwargs = dict(log_requests=True) # will log the request url and response data when retrieving
auth = ads.auth.create_signer(signer_callable=signer_callable, signer_kwargs=signer_kwargs)

AuthContext context class can also be used to specify the desired type of authentication. It supports API key configuration, resource principal, and instance principal authentication, as well as predefined signers, callable signers, or API keys configurations from specified locations. See API Documentation for more details.