Configuration

Authenticating to the Oracle Cloud Infrastructure APIs from a Notebook Session

When you are working within a notebook session, you are operating as the Linux user datascience. This user does not have an Oracle Cloud Infrastructure 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 and models and the resources of other Oracle Cloud Infrastructure service, such as Object Storage, Functions, Vault, Data Flow, and so on. To access these resources from the notebook environment, you must use one of the two provided authentication approaches:

1. Authenticating using your Notebook Session’s Resource Principal (Recommended Moving Forward)

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 Oracle Cloud Infrastructure resources. When compared to using the Oracle Cloud Infrastructure configuration and key files approach, using resource principals provides a more secure and easy way to authenticate to the Oracle Cloud Infrastructure APIs.

Within your notebook session, you can choose to use the resource principal to authenticate while using Oracle’s Accelerated Data Science (ADS) SDK by running ads.set_auth(auth='resource_principal') in a notebook cell. For example, run:

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 Oracle Cloud Infrastructure configuration and key files (Default)

You can also authenticate as your own personal IAM user by creating or uploading a Oracle Cloud Infrastructure configuration and key files inside of the notebook session environment. The Oracle Cloud Infrastructure configuration file contains the necessary credentials to authenticate your user against the model catalog and other Oracle Cloud Infrastructure services like Object Storage.

We have included a getting-started.ipynb notebook in the home directory of the notebook session environment. This notebook provides all the steps needed to create the configuration file and the keys. Follow the steps in that notebook before importing and using ADS in your notebooks.

Note

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

Setup for ADB

There are two different configurations of the Autonomous Database (ADB). They are the Autonomous Data Warehouse (ADW) and the Autonomous Transaction Processing (ATP) database. The steps to connect to ADW and ATP are the same. To access an instance of the ADB from the notebook environment, you need the client credentials and connection information. The client credentials include the wallet, which is required for all types of connections.

Use these steps to access Oracle ADB:

1. On the page ADW or ATP instance you want to load dataset from, click DB Connection.

2. Download the Wallet file by clicking Download Wallet. You need to create a password to for the Wallet to download it. You do not need this password to connect from the notebook.

3. Unzip the wallet.

4. Create a <path_to_wallet_folder> folder for your wallet on the notebook environment environment.

5. Upload your wallet files into the <path_to_wallet_folder> folder using the Jupyterlab Upload Files button:

6. Open the sqlnet.ora file from the wallet files, then configure the METHOD_DATA to be:

METHOD_DATA = (DIRECTORY="<path_to_wallet_folder>")

7. To find the location of the sqlnet.ora file, the TNS_ADMIN environment variable must point to that location. We suggest that you create a Python dictionary to store all of the connection information. In this example, this dictionary is called creds. It is generally poor security practice to store credentials in your notebook. We recommend that you use the notebook ads-examples/ADB_working_with.ipynb demonstrates how to store them outside the notebook in a configuration file.

   The environment variable should be set in your notebooks, for example:

# Replace with your TNS_ADMIN value here:
creds = {}
creds['tns_admin'] = <path_to_wallet_folder>
os.environ['TNS_ADMIN'] = creds['tns_admin']

8. You can find SID names from the tnsname.ora file in the wallet file. Create a dictionary to manage your credentials. In this example, the variable creds is used. The SID is an identifier that identifies the consumer group of the the Oracle Database:

# Replace with your SID name here:
creds['sid'] = <your_SID_name>

9. Ask your database administrator for the username & password and add them to your creds dictionary. For example:

creds['user'] = <database_user>
creds['password'] = <database_password>

10. Test the connection to the ADB by running these commands:

os.environ['TNS_ADMIN'] = creds['tns_admin']
connect = 'sqlplus ' + creds['user'] + '/' + creds['password'] + '@' + creds['sid']
print(os.popen(connect).read())

Messages similar to the following are displayed if the connection is successful:

An introduction to loading data from ADB into ADS using cx_Oracle and ``SQLAlchemy``n is in Loading Data.