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: .. code-block:: python 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: .. code-block:: python import ads ads.set_auth(auth='instance_principal') mc = ModelCatalog(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: .. code-block:: python import ads ads.set_auth(auth='security_token') mc = ModelCatalog(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. .. code-block:: python 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 `_. .. code-block:: python 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. .. code-block:: python 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: .. code-block:: python 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 <../../ads.common.html#ads.common.auth.AuthContext>`__ for more details.