Use Amazon Resource Names (ARNs) to Access AWS Resources

You can use Amazon Resource Names (ARNs) to access AWS resources with Autonomous Database.

About Using Amazon Resource Names (ARNs) to Access AWS Resources
When you use ARN role based authentication with Autonomous Database, you can securely access AWS resources without creating and saving credentials based on long-term AWS IAM access keys.
Perform AWS Management Prerequisites to Use Amazon Resource Names (ARNs)
Using the AWS Management Console or using the APIs, create an AWS user, role, policies, and trust relationship. You perform these steps before you use with DBMS_CLOUD.CREATE_CREDENTIAL to create a credential with an ARN parameter on Autonomous Database.
Perform Autonomous Database Prerequisites to Use Amazon ARNs
Prior to using an AWS resource with DBMS_CLOUD.CREATE_CREDENTIAL with an ARN parameter, the ADMIN user must enable ARN on the Autonomous Database instance.
Create Credentials with ARN Parameters to Access AWS Resources
After ARN usage is enabled for the Autonomous Database instance and the ARN is configured by the AWS administrator, on Autonomous Database you can create a credential object with ARN parameters.
Update Credentials with ARN Parameters for AWS Resources
The ARN credentials you use on Autonomous Database work with the AWS token service that enables you to use temporary role based credentials to access to AWS resources from Autonomous Database.

Parent topic: Configure Policies and Roles to Access Resources

About Using Amazon Resource Names (ARNs) to Access AWS Resources

When you use ARN role based authentication with Autonomous Database, you can securely access AWS resources without creating and saving credentials based on long-term AWS IAM access keys.

For example, you may want to load data from an AWS S3 bucket into your Autonomous Database, perform some operation on the data, and then write the modified data back to the S3 bucket. You can do this without using an ARN if you have AWS user credentials to access the S3 bucket. However, using role-based ARNs to access AWS resources from Autonomous Database has the following benefits:

You can create role-based access, with different policies for different users or schemas that need access to AWS resources from an Autonomous Database instance. This allows you to set a policy to limit access to AWS resources by role. For example, setting a policy limiting to read-only access, by role, to an S3 bucket.
ARN based credentials provide better security as you do not need to provide long-term AWS user credentials in code to access AWS resources. Autonomous Database manages the temporary credentials generated from the AWS Assume Role Operation.

Steps to Configure ARN Usage with Autonomous Database

Before creating a credential using an ARN in Autonomous Database, in AWS, your account administrator must define a policy that allows you to access AWS resources, such as an S3 bucket. By default, ARN credential services are not enabled on Autonomous Database. The ADMIN user enables ARN credentials for the necessary user which allows them to create and use ARN credentials on the Autonomous Database instance.

In AWS, the role ARN is the identifier for the provided access and can be viewed on the AWS console. For added security, when the AWS administrator configures the role, policies, and trust relationship for the AWS account, they must also configure an External ID in the role's trust relationship.

The External ID provides additional protection for assuming roles. The AWS administrator configures configure the External ID as one of the following, based on the Autonomous Database instance:

The compartment OCID
The database OCID
The tenancy OCID

On AWS, the role can only be assumed by trusted users that are identified by the External ID included in the request URL, where the supplied External ID in the request matches the External ID configured in the role's trust relationship.

Note:

Setting the External ID is required for security.

The following figure outlines the configuration steps:

Description of adb_arn_config_steps.eps follows

Description of the illustration adb_arn_config_steps.eps

Steps to Use ARNs with DBMS_CLOUD

Each AWS resource has its own identity, and the resource authenticates with the Autonomous Database instance using a DBMS_CLOUD credential that you create with parameters that identify the ARN. Autonomous Database creates and secures the principal credentials you use to access AWS resources.

To create a credential with ARN parameters to access AWS resources:

Perform prerequisite steps in the AWS Account: In your AWS account, from the AWS Management Console or using the CLI, create the roles and policies for the ARN that you use with Autonomous Database and update the trust relationship for the role. The Oracle user ARN is configured when the trust relationship for the role is updated.

See Perform AWS Management Prerequisites to Use Amazon Resource Names (ARNs) for more information.
Perform prerequisite steps on Autonomous Database: On Autonomous Database you must enable the ADMIN user or another user to use credentials with ARN parameters to access AWS resources.

See Perform Autonomous Database Prerequisites to Use Amazon ARNs for more information.
Create credentials with DBMS_CLOUD.CREATE_CREDENTIAL and supply the parameters that identify an AWS role. Using the credential object, Autonomous Database can access AWS resources as specified in the policies defined for the role in the AWS account.

See Create Credentials with ARN Parameters to Access AWS Resources for details on these steps.
Use the credential object you created in the previous step with a DBMS_CLOUD procedure or function that takes a credential parameter, such as DBMS_CLOUD.COPY_DATA or DBMS_CLOUD.LIST_OBJECTS.

Parent topic: Use Amazon Resource Names (ARNs) to Access AWS Resources

Perform AWS Management Prerequisites to Use Amazon Resource Names (ARNs)

Using the AWS Management Console or using the APIs, create an AWS user, role, policies, and trust relationship. You perform these steps before you use with DBMS_CLOUD.CREATE_CREDENTIAL to create a credential with an ARN parameter on Autonomous Database.

To use an ARN to access AWS resources your AWS administrator defines the policies and a principal that allows you to access AWS resources. For example, while using Autonomous Database you might want to access data from an S3 bucket, perform some operation on the data, and then write the modified data back to the S3 bucket.

Note:

Depending on your existing AWS configuration and the External ID you use, you do not need to create a new role and policy for each Autonomous Database instance. If you already have an AWS role containing the necessary policy to access a resource, for example to access S3 cloud storage, you can modify the trust relationship to include the details in Step 3. Likewise, if you already have a role with the necessary trust relationship, you can use that role to access all of your databases in an OCI compartment or tenancy if you use an external ID that specifies the compartment OCID or tenancy OCID.

From the AWS Management Console or using the APIs, an AWS administrator performs the following steps:

Create a policy. In the policy you specify permissions for accessing AWS resources such as S3 buckets.

See Creating an IAM policy to access Amazon S3 resources for more information.
Create a role and attach the policy to the role.
1. Access the AWS Management Console and choose Identity and Access Management (IAM).
2. Click Create role.
  
  Description of the illustration arn_aws_create_role_button.png
3. Select Another AWS account.
  
  Description of the illustration arn_aws_create_role_aws_account.png
4. Enter your Account ID.
  You use this as a temporary value. Later you replace this with the Account ID you use to access AWS resources.
5. In the Options area select Require external ID and enter a temporary external ID, such as 0000. Later you replace this external ID with a valid value.
6. Click Next Permissions to attach the Policies you created in Step 1 or other policies you want to apply to the role.
7. Click Next Tags and apply or create tags as needed for the role.
8. Click Next Review and add a Role Name and Role Description.
9. Click Create Role.
You use the role's ARN with DBMS_CLOUD.CREATE_CREDENTIAL to create credential objects with ARN parameters to access AWS resources.

See Creating a role to delegate permissions to an IAM user for more information.
Specify a Trust Relationship for the role.
1. From the Roles list, under Role name, select the role you created.
2. On the roles Summary page for the selected role, select the Trust relationships tab.
  
  Description of the illustration arn_aws_create_role_aws_trust.png
3. In the trust relationship, click Edit trust relationship.
  
  Description of the illustration arn_aws_create_role_aws_trust_set.png
4. Edit the trust relationship to specify the Principal parameter AWS.
  
  This AWS user ARN is available in the CLOUD_INTEGRATIONS view. See Perform Autonomous Database Prerequisites to Use Amazon ARNs for more information.
5. Edit the trust relationship to specify the External ID.
  On Autonomous Database when you create an AWS ARN credential with DBMS_CLOUD.CREATE_CREDENTIAL or when you enable AWS ARN with DBMS_CLOUD_ADMIN.ENABLE_PRINCIPAL_AUTH, by default the external_id_type parameter value is database_ocid. Optionally you can set the external_id_type value to one of the supported values: database_ocid, compartment_ocid, or tenant_ocid.
  
  When you use the database OCID as the External ID, the policy's trust relationship only trusts the Autonomous Database instance specified with the OCID. If you use a compartment OCID, the policy's trust relationship trusts all the Autonomous Database instances in the compartment and you can use the same role ARN to grant access to AWS resources to any Autonomous Database in the specified compartment. Likewise, if you use the tenancy OCID, you can use the same role ARN to grant access to AWS resources to any Autonomous Database in the specified tenancy.
  
  Previously in Step 2 you set the trust relationship External ID to the temporary value 0000.
  
  On AWS you configure the trust relationship External ID value to match one of the following:
  - When the external_id_type type is database_ocid, on AWS you configure the role's trust relationship External ID to be the Database OCID.
    
    The Database OCID is available by running the following query:
```
SELECT cloud_identity FROM v$pdbs;
```
    See Obtain Tenancy Details for more information.
  - When the external_id_type type is compartment_ocid, on AWS you configure the role's trust relationship External ID to be the Compartment OCID.
    
    The Compartment OCID is available on the Compartment details page from the Oracle Cloud Infrastructure Console. To find the Compartment details page, from the Oracle Cloud Infrastructure left navigation menu click Identity & and Security and then select Compartments. Select the compartment that contains the Autonomous Database instance to see the Compartment ID.
  - When the external_id_type type is tenant_ocid, on AWS you configure the role's trust relationship External ID to be the Tenancy OCID.
    
    The Tenancy OCID is available on the Tenancy details page from the Oracle Cloud Infrastructure Console. To find the Tenancy details page, from the Oracle Cloud Infrastructure left navigation menu click Governance & Administration and then select Tenancy Details. The Tenancy Information tab shows the Tenancy OCID.
  - When you set the value for ExternalID, by default the OCID value must be in upper case. If you want to supply the OCID in lower case, set the condition "StringEqualsIgnoreCase" instead of "StringEquals" in the JSON when you edit the trust relationship.
  Description of the illustration arn_aws_create_role_aws_trust_final.png
See How to use trust policies with IAM role and How to use an external ID when granting access to your AWS resources to a third party for more information.

After the ARN role configuration is finished, you can enable ARN on the instance. See Perform Autonomous Database Prerequisites to Use Amazon ARNs for more information.

Parent topic: Use Amazon Resource Names (ARNs) to Access AWS Resources

Perform Autonomous Database Prerequisites to Use Amazon ARNs

Prior to using an AWS resource with DBMS_CLOUD.CREATE_CREDENTIAL with an ARN parameter, the ADMIN user must enable ARN on the Autonomous Database instance.

By default, ARN credential services are not enabled on Autonomous Database. The ADMIN user runs the procedure DBMS_CLOUD_ADMIN.ENABLE_PRINCIPAL_AUTH to enable the ADMIN user or other users to create credentials with ARN parameters.

Enable the use of ARN credentials on the Autonomous Database instance.

BEGIN
    DBMS_CLOUD_ADMIN.ENABLE_PRINCIPAL_AUTH(
        username => 'adb_user',
        params => JSON_OBJECT( 
                'aws_role_arn' value 'arn:aws:iam::123456:role/AWS_ROLE_ARN'));
END;
/

If you want the specified user to have privileges to enable ARN credentials for other users, set the params parameter grant_option to TRUE.

For example:

BEGIN
DBMS_CLOUD_ADMIN.ENABLE_PRINCIPAL_AUTH(
     username => 'adb_user',
     params => JSON_OBJECT(
                     'aws_role_arn' value 'arn:aws:iam::123456:role/AWS_ROLE_ARN',
                     'grant_option' value TRUE ));
END;
/

After you run this command, adb_user has privileges to enable ARN credentials for other users.

For example, if you connect as adb_user, you can run the following command:

BEGIN
    DBMS_CLOUD_ADMIN.ENABLE_PRINCIPAL_AUTH(
        username => 'adb_user2'); 
END;
/

See ENABLE_PRINCIPAL_AUTH Procedure for more information.

Query the CLOUD_INTEGRATIONS view to obtain Oracle's AWS user ARN.
```
SELECT param_value FROM CLOUD_INTEGRATIONS
        WHERE param_name = 'aws_user_arn';

PARAM_VALUE
--------------------------------------------  
arn:aws:iam::account-ID:user/username
```
The view CLOUD_INTEGRATIONS is available to the ADMIN user or to a user with DWROLE privileges.

The AWS administrator uses the aws_user_arn value when configuring the AWS role's trust relationship with the role and policies on the AWS system. Providing this value grants permission on the AWS side for DBMS_CLOUD to access AWS resources.

After you enable ARN on the Autonomous Database instance by running DBMS_CLOUD_ADMIN.ENABLE_PRINCIPAL_AUTH, the credential named AWS$ARN is available to use with any DBMS_CLOUD API that takes a credential as the input. Except for the credential named AWS$ARN, you can also create additional credentials with ARN parameters to access AWS resources. See Create Credentials with ARN Parameters to Access AWS Resources for more information.

Parent topic: Use Amazon Resource Names (ARNs) to Access AWS Resources

Create Credentials with ARN Parameters to Access AWS Resources

After ARN usage is enabled for the Autonomous Database instance and the ARN is configured by the AWS administrator, on Autonomous Database you can create a credential object with ARN parameters.

Autonomous Database creates and secures the principal credentials you use to access the Amazon resources when you supply the credential object with DBMS_CLOUD procedures and functions.

To use Amazon resources with Autonomous Database, do the following:

Create credentials using the procedure DBMS_CLOUD.CREATE_CREDENTIAL with the params parameter to specify the ARN value. For example:
```
BEGIN
  DBMS_CLOUD.CREATE_CREDENTIAL(
    credential_name => 'DEF_CRED_ARN',
    params =>
        JSON_OBJECT('aws_role_arn' value 'arn:aws:iam::123456:role/AWS_ROLE_ARN',                                            
                    'external_id_type' value 'database_ocid')
  );
END;
/
```
This operation creates the credentials in the database in an encrypted format. You can use any name for the credential name.

For detailed information about the parameters, see CREATE_CREDENTIAL Procedure.

Use a DBMS_CLOUD procedure to access an Amazon resource with the ARN credentials.

For example, use DBMS_CLOUD.LIST_OBJECTS.

SELECT object_name FROM DBMS_CLOUD.LIST_OBJECTS(
           credential_name => 'DEF_CRED_ARN',
           location_uri    => 'https://my-bucket.s3.us-west-2.amazonaws.com/');

Parent topic: Use Amazon Resource Names (ARNs) to Access AWS Resources

Update Credentials with ARN Parameters for AWS Resources

The ARN credentials you use on Autonomous Database work with the AWS token service that enables you to use temporary role based credentials to access to AWS resources from Autonomous Database.

When an AWS Administrator revokes the policies, roles, or trust relationship, you need to either update the credentials or create new credentials to access the AWS resources.

Perform the following steps to update credentials:

Use DBMS_CLOUD.UPDATE_CREDENTIAL to update an ARN based credential to supply a new ARN value.
```
BEGIN
  DBMS_CLOUD.UPDATE_CREDENTIAL(
     credential_name => 'DEF_CRED_ARN',
     attribute => 'aws_role_arn',
     value => 'new_ARN_value'); 
END;
/
```
This updates the aws_role_arn attribute to the new value new_ARN_value for the credential named DEF_CRED_ARN.
Use DBMS_CLOUD.UPDATE_CREDENTIAL to update an ARN based credential to update the attribute external_id_type value.
```
BEGIN
  DBMS_CLOUD.UPDATE_CREDENTIAL(
     credential_name => 'DEF_CRED_ARN',
     attribute => 'external_id_type',
     value => 'compartment_ocid'); 
END;
/
```
This updates the external_id_type attribute value to the value compartment_ocid.

See UPDATE_CREDENTIAL Procedure and CREATE_CREDENTIAL Procedure for more information.

Parent topic: Use Amazon Resource Names (ARNs) to Access AWS Resources