Managing User Credentials

This topic describes the basics of working with Oracle Cloud Infrastructure Identity and Access Management (IAM) user credentials. If you're not already familiar with the available credentials, see User Credentials.

Working with Console Passwords and API Keys

Each user automatically has the ability to change or reset their own Console password, as well as manage their own API keys. An administrator does not need to create a policy to give a user those abilities.

To manage credentials for users other than yourself, you must be in the Administrators group or some other group that has permission to work with the tenancy. Having permission to work with a compartment within the tenancy is not sufficient. For more information, see The Administrators Group and Policy.

IAM administrators (or anyone with permission to the tenancy) can use either the Console or the API to manage all aspects of both types of credentials, for themselves and all other users. This includes creating an initial one-time password for a new user, resetting a password, uploading API keys, and deleting API keys.

Users who are not administrators can manage their own credentials. In the Console, users can:

  • Change or reset their own password.
  • Upload an API key in the Console for their own use (and also delete their own API keys).

And with the API, users can:

  • Reset their own password with CreateOrResetUIPassword.
  • Upload an additional API key to the IAM service for their own use with UploadApiKey (and also delete their own API keys with DeleteApiKey). Remember that a user can't use the API to change or delete their own credentials until they themselves upload a key in the Console, or an administrator uploads a key for that user in the Console or the API.

A user can have a maximum of three API keys at a time.

Working with Auth Tokens

Note

"Auth tokens" were previously named "Swift passwords". Any Swift passwords you had created are now listed in the Console as auth tokens. You can continue to use the existing passwords.

Auth tokens are Oracle-generated token strings that you can use to authenticate with third-party APIs that do no support Oracle Cloud Infrastructure's signature-based authentication. Each user created in the IAM service automatically has the ability to create, update, and delete their own auth tokens in the Console or the API. An administrator does not need to create a policy to give a user those abilities. Administrators (or anyone with permission to the tenancy) also have the ability to manage auth tokens for other users.

Note that you cannot change your auth token to a string of your own choice. The token is always an Oracle-generated string.

Auth tokens do not expire. Each user can have up to two auth tokens at a time. To get an auth token in the Console, see To create an auth token.

Using an Auth Token with Swift

Swift is the OpenStack object store service. If you already have an existing Swift client, you can use it with the Recovery Manager (RMAN) to back up an Oracle Database System (DB System) database to Object Storage. You will need to get an auth token to use as your Swift password. When you sign in to your Swift client, you provide the following:

  • Your Oracle Cloud Infrastructure Console user login
  • Your Swift-specific auth token, provided by Oracle
  • Your organization's Oracle tenant name

Any user of a Swift client that integrates with Object Storage needs permission to work with the service. If you're not sure if you have permission, contact your administrator. For information about policies, see How Policies Work. For basic policies that enable use of Object Storage, see Common Policies.

Working with Customer Secret Keys

Note

"Customer Secret keys" were previously named "Amazon S3 Compatibility API keys". Any keys you had created are now listed in the Console as Customer Secret keys. You can continue to use the existing keys.

Object Storage provides an API to enable interoperability with Amazon S3. To use this Amazon S3 Compatibility API, you need to generate the signing key required to authenticate with Amazon S3. This special signing key is an Access Key/Secret Key pair. Oracle provides the Access Key that is associated with your Console user login. You or your administrator generates the Customer Secret key to pair with the Access Key.

Each user created in the IAM service automatically has the ability to create, update, and delete their own Customer Secret keys in the Console or the API. An administrator does not need to create a policy to give a user those abilities. Administrators (or anyone with permission to the tenancy) also have the ability to manage Customer Secret keys for other users.

Any user of the Amazon S3 Compatibility API with Object Storage needs permission to work with the service. If you're not sure if you have permission, contact your administrator. For information about policies, see How Policies Work. For basic policies that enable use of Object Storage, see Common Policies.

Customer Secret keys do not expire. Each user can have up to two Customer Secret keys at a time. To create keys using the Console, see To create a Customer Secret key.

Working with OAuth 2.0 Client Credentials

Note

OAuth 2.0 Client Credentials are not available in the following realms :
  • the commercial realm (OC1)
  • the United Kingdom Government Cloud (OC4)
OAuth 2.0 client credentials are required to interact programmatically with those services that use the OAuth 2.0 authorization protocol. The credentials enable you to obtain a secure token to access those service REST API endpoints. The allowed actions and endpoints granted by the token depend on the scopes (permissions) that you select when you generate the credentials. The services that use the OAuth 2.0 protocol are:
  • Oracle Analytics Cloud
  • Oracle Integration

An OAuth 2.0 access token is valid for 3600 seconds (1 hour).

To create the credentials, you need to know the service resource and scope. Typically, you can select these from a drop-down list. However, if the information is not available in the list, you can manually enter the resource and scope. The scope defines the allowed permissions for the token, so ensure to set the scope at the minimum required access level.

A user can create the credentials for themselves or an Administrator can create the credentials for another user. The lists of available resources and scopes display only those resources and permission levels that the user has been granted access to.

OAuth 2.0 Client Credential Limits

Each user can have up to 10 OAuth 2.0 client credentials. You can increase this limit by Requesting a Service Limit Increase.

Each OAuth 2.0 client credential can have up to 10 scopes.

Obtaining an OAuth 2.0 Access Token

To obtain the token, use your credentials in a request against the OAuth2 token service endpoint as follows:

  1. Create the OAuth 2.0 client credentials. See To create OAuth 2.0 client credentials.

    After you create the OAuth 2.0 client credential note the following information:

    • The generated secret
    • The OCID of the OAuth 2.0 client credential
    • The scope and audience (fully-qualifed scope)
  2. Using the information from the previous step, make a request against the /oauth2/token endpoint to obtain a token as follows:
    curl -k -X POST -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" --user '<Oauth 2.0 client credential OCID>:<credential secret>'  https://auth.<oci_region>.oraclecloud.com/oauth2/token -d 'grant_type=client_credentials&scope=<audience>-<scope>'

Where:

  • <Oauth 2.0 client credential OCID>:<credential secret> is the OCID of the OAuth 2.0 client credential that you created joined by a colon (:) with the generated secret for the credential. Note that this secret is only displayed at the time you generate it and it must be copied immediately. You can retrieve the OCID from the details of the credential at any time.
  • https://auth.<oci_region>.oraclecloud.com/oauth2/token is the Oracle Cloud Infrastructure OAuth 2.0 authorization endpoint where <OCI_region> is a region your tenancy is subscribed to. For example, us-ashburn-1.
  • <scope>-<audience> is the fully-qualifed scope, that is, the scope and audience joined by a hyphen (-). The scope and audience are available from the details page of the credential.

Example request:

curl -k -X POST -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" --user 'ocid1.credential.region1..aaaaaaexamplestringaapgpedxq:{SAMplESeCreta5y'  https://auth.us-ashburn-1.oraclecloud.com/oauth2/token -d 'grant_type=client_credentials&scope=https://2aexampley3uytc.analytics.ocp.oraclecloud.com-urn:opc:resource:consumer::all'

The response will include the token. Example response:

{
"access_token" : "eyJraWQiOiJhcDVfwqKdi...8lTILrzc4cof2A",
"token_type" : "Bearer",
"expires_in" : "3600"
}

The token string is truncated in the example response. Copy the entire access_token string (within the quotation marks) as shown in your response.

Using the OAuth 2.0 Token in a Request

After you obtain an OAuth 2.0 access token, you provide the token in a bearer token header of the REST API request.

For example:

curl -i -X GET -H "Authorization: Bearer <token-string>" "https://<audience>/<rest-endpoint-path>"

What to Do When the Token Expires

The token expires after 3600 seconds (1 hour). When the token expires, request a new token following the instructions in Obtaining an OAuth 2.0 Access Token.

Adding Scopes

You can add scopes to an existing OAuth 2.0 client credential to add access to more services with the same credential. After you add scopes, you do not need to regenerate the secret.

To request a token for multiple scopes, You can include additional scopes in a token request by appending

&scope=<scope>-<<audience>

to the final argument of the request and specifying the scope and audience for the scope you want to add.

Working with SMTP Credentials

Simple Mail Transfer Protocol (SMTP) credentials are needed in order to send email through the Email Delivery service. Each user is limited to a maximum of two SMTP credentials. If more than two are required, they must be generated on other existing users or additional users must be created.

Note

You cannot change your SMTP username or password to a string of your own choice. The credentials are always Oracle-generated strings.

Each user created in the IAM service automatically has the ability to create and delete their own SMTP credentials in the Console or the API. An administrator does not need to create a policy to give a user those abilities. Administrators (or anyone with permission to the tenancy) also have the ability to manage SMTP credentials for other users.

Tip

Although each user can create and delete their own credentials, it is a security best practice to create a new user and generate SMTP credentials on this user rather than generating SMTP credentials on your Console user that already has permissions assigned to it.

SMTP credentials do not expire. Each user can have up to two credentials at a time. To get SMTP credentials in the Console, see To generate SMTP credentials.

For information about using the Email Delivery service, see Overview of the Email Delivery Service.

Using the Console

To change your Console password

You're prompted to change your initial one-time password the first time you sign in to the Console. The following procedure is for changing your password again later.

Note

For Federated Users

If your company uses an identity provider (other than Oracle Identity Cloud Service) to manage user logins and passwords, you can't use the Console to update your password. You do that with your identity provider.

  1. Sign in to the Console using the Oracle Cloud Infrastructure Username and Password.
  2. After you sign in, go to the top-right corner of the Console, open the Profile menu (User menu icon) and then click Change Password.

    This screenshot shows the Change Password link on the user menu

  3. Enter the current password.
  4. Follow the prompts to enter the new password, and then click Save New Password.
To create or reset another user's Console password

If you're an administrator, you can use the following procedure to create or reset a user's password. The procedure generates a new one-time password that the user must change the next time they sign in to the Console.

  1. View the user's details: In the Console, click Identity, and then click Users. Locate the user in the list, and then click the user's name to view the details.
  2. Click Create/Reset Password.

    The new one-time password is displayed. If you're an administrator performing the task for another user, you need to securely deliver the new password to the user. The user will be prompted to change their password the next time they sign in to the Console. If they don't change it within 7 days, the password will expire and you'll need to create a new one-time password for the user.

To reset your password if you forgot it

If you have an email address in your user profile, you can use the Forgot Password link on the sign on page to have a temporary password sent to you. If you don't have an email address in your user profile, you must ask an administrator to reset your password for you.

To unblock a user

If you're an administrator, you can unblock a user who has tried 10 times in a row to sign in to the Console unsuccessfully. See To unblock a user.

To add an API signing key

You can use the Console to generate the private/public key pair for you. If you already have a key pair, you can choose to upload the public key. When you use the Console to add the key pair, the Console also generates a configuration file preview snippet for you.

The following procedures work for a regular user or an administrator. Administrators can manage API keys for either another user or themselves.

About the Config File Snippet

When you use the Console to add the API signing key pair, a configuration file preview snippet is generated with the following information:

  • user - the OCID of the user for whom the key pair is being added.
  • fingerprint - the fingerprint of the key that was just added.
  • tenancy - your tenancy's OCID.
  • region - the currently selected region in the Console.
  • key_file- the path to your downloaded private key file. You must update this value to the path on your file system where you saved the private key file.

If your config file already has a DEFAULT profile, you'll need to do one of the following:

  • Replace the existing profile and its contents.
  • Rename the existing profile.
  • Rename this profile to a different name after pasting it into the config file.

You can copy this snippet into your config file, to help you get started. If you don't already have a config file, see SDK and CLI Configuration File for details on how to create one. You can also retrieve the config file snippet later for an API signing key whenever you need it. See: To get the config file snippet for an API signing key.

To generate an API signing key pair

Prerequisite: Before you generate a key pair, create the .oci directory in your home directory to store the credentials. See SDK and CLI Configuration File for more details.

  1. View the user's details:
    • If you're adding an API key for yourself:

      Open the Profile menu (User menu icon) and click User Settings.

    • If you're an administrator adding an API key for another user: In the Console, click Identity, and then click Users. Locate the user in the list, and then click the user's name to view the details.
  2. Click Add API Key.
  3. In the dialog, select Generate API Key Pair.
  4. Click Download Private Key and save the key to your .oci directory. In most cases, you do not need to download the public key.

    Note: If your browser downloads the private key to a different directory, be sure to move it to your .oci directory.

  5. Click Add.

    The key is added and the Configuration File Preview is displayed. The file snippet includes required parameters and values you'll need to create your configuration file. Copy and paste the configuration file snippet from the text box into your ~/.oci/config file. (If you have not yet created this file, see SDK and CLI Configuration File for details on how to create one.)

    After you paste the file contents, you'll need to update the key_file parameter to the location where you saved your private key file.

    If your config file already has a DEFAULT profile, you'll need to do one of the following:
    • Replace the existing profile and its contents.
    • Rename the existing profile.
    • Rename this profile to a different name after pasting it into the config file.
  6. Update the permissions on your downloaded private key file so that only you can view it:
    1. Go to the .oci directory where you placed the private key file.
    2. Use the command chmod go-rwx ~/.oci/<oci_api_keyfile>.pem to set the permissions on the file.
To upload or paste an API key

Prerequisite: You have generated a public RSA key in PEM format (minimum 2048 bits). The PEM format looks something like this:

-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAoTFqF...
...
-----END PUBLIC KEY——
  1. View the user's details:
    • If you're adding an API key for yourself:

      Open the Profile menu (User menu icon) and click User Settings.

    • If you're an administrator adding an API key for another user: In the Console, click Identity, and then click Users. Locate the user in the list, and then click the user's name to view the details.
  2. Click Add API Key.
  3. In the dialog, select Choose Public Key File to upload your file, or Paste Public Key, if you prefer to paste it into a text box
  4. Click Add.

    The key is added and the Configuration File Preview is displayed. The file snippet includes required parameters and values you'll need to create your configuration file. Copy and paste the configuration file snippet from the text box into your ~/.oci/config file. (If you have not yet created this file, see SDK and CLI Configuration File for details on how to create one.)

    After you paste the file contents, you'll need to update the key_file parameter to the location where you saved your private key file.

    If your config file already has a DEFAULT profile, you'll need to do one of the following:

    • Replace the existing profile and its contents.
    • Rename the existing profile.
    • Rename this profile to a different name after pasting it into the config file.
To get the config file snippet for an API signing key
The following procedure works for a regular user or an administrator.
  1. View the user's details:
    • If you're getting an API key config file snippet for yourself:

      Open the Profile menu (User menu icon) and click User Settings.

    • If you're an administrator getting an API key config file snippet for another user: In the Console, click Identity, and then click Users. Locate the user in the list, and then click the user's name to view the details.
  2. On the left side of the page, click API Keys. The list of API key fingerprints is displayed.
  3. Click the the Actions icon (three dots) for the fingerprint, and select View configuration file.

    The Configuration File Preview is displayed. The file snippet includes required parameters and values you'll need to create your configuration file. Copy and paste the configuration file snippet from the text box into your ~/.oci/config file. (If you have not yet created this file, see SDK and CLI Configuration File for details on how to create one.) After you paste the file contents, you'll need to update the key_file parameter to the location where you saved your private key file.

    If your config file already has a DEFAULT profile, you'll need to do one of the following:
    • Replace the existing profile and its contents.
    • Rename the existing profile.
    • Rename this profile to a different name after pasting it into the config file.
To delete an API signing key
The following procedure works for a regular user or an administrator. Administrators can delete an API key for either another user or themselves.
  1. View the user's details:
    • If you're deleting an API key for yourself:

      Open the Profile menu (User menu icon) and click User Settings.

    • If you're an administrator deleting an API key for another user: In the Console, click Identity, and then click Users. Locate the user in the list, and then click the user's name to view the details.
  2. For the API key you want to delete, click Delete.
  3. Confirm when prompted.
The API key is no longer valid for sending API requests.
To create an auth token
  1. View the user's details:
    • If you're creating an auth token for yourself:

      Open the Profile menu (User menu icon) and click User Settings.

    • If you're an administrator creating an auth token for another user: In the Console, click Identity, and then click Users. Locate the user in the list, and then click the user's name to view the details.
  2. On the left side of the page, click Auth Tokens.
  3. Click Generate Token.
  4. Enter a description that indicates what this token is for, for example, "Swift password token".
  5. Click Generate Token.

    The new token string is displayed.

  6. Copy the token string immediately, because you can't retrieve it again after closing the dialog box.

If you're an administrator creating an auth token for another user, you need to securely deliver it to the user by providing it verbally, printing it out, or sending it through a secure email service.

To delete an auth token

The following procedure works for a regular user or an administrator. Administrators can delete an auth token for either another user or themselves.

  1. View the user's details:
    • If you're deleting an auth token for yourself:

      Open the Profile menu (User menu icon) and click User Settings.

    • If you're an administrator deleting an auth token for another user: In the Console, click Identity, and then click Users. Locate the user in the list, and then click the user's name to view the details.
  2. On the left side of the page, click Auth Tokens.
  3. For the auth token you want to delete, click Delete.
  4. Confirm when prompted.

The auth token is no longer valid for accessing third-party APIs.

To create a Customer Secret key
  1. View the user's details:
    • If you're creating a Customer Secret key for yourself:

      Open the Profile menu (User menu icon) and click User Settings.

    • If you're an administrator creating a Customer Secret key for another user: In the Console, click Identity, and then click Users. Locate the user in the list, and then click the user's name to view the details.
  2. On the left side of the page, click Customer Secret Keys.

    A Customer Secret key consists of an Access Key/Secret key pair. Oracle automatically generates the Access Key when you or your administrator generates the Secret Key to create the Customer Secret key.

  3. Click Generate Secret Key.
  4. Enter a friendly description for the key and click Generate Secret Key.

    The generated Secret Key is displayed in the Generate Secret Key dialog box. At the same time, Oracle generates the Access Key that is paired with the Secret Key. The newly generated Customer Secret key is added to the list of Customer Secret Keys.

  5. Copy the Secret Key immediately, because you can't retrieve the Secret Key again after closing the dialog box for security reasons.

    If you're an administrator creating a Secret Key for another user, you need to securely deliver it to the user by providing it verbally, printing it out, or sending it through a secure email service.

  6. Click Close.
  7. To show or copy the Access Key, click the Show or Copy action to the left of the Name of a particular Customer Secret key.
To delete a Customer Secret key

The following procedure works for a regular user or an administrator. Administrators can delete a Customer Secret key for either another user or themselves.

  1. View the user's details:
    • If you're deleting a Customer Secret key for yourself:

      Open the Profile menu (User menu icon) and click User Settings.

    • If you're an administrator deleting a Customer Secret key for another user: In the Console, click Identity, and then click Users. Locate the user in the list, and then click the user's name to view the details.
  2. On the left side of the page, click Customer Secret Keys.
  3. For the Customer Secret key you want to delete, click Delete.
  4. Confirm when prompted.

The Customer Secret key is no longer available to use with the Amazon S3 Compatibility API.

To create OAuth 2.0 client credentials
Note

OAuth 2.0 Client Credentials are not available in the following realms :
  • the commercial realm (OC1)
  • the United Kingdom Government Cloud (OC4)
  1. View the user's details:
    • If you're creating an OAuth 2.0 client credential for yourself:

      Open the Profile menu (User menu icon) and click User Settings.

    • If you're an administrator creating an OAuth 2.0 client credential for another user: In the Console, click Identity, and then click Users. Locate the user in the list, and then click the user's name to view the details.
  2. On the left side of the page, click OAuth 2.0 Client Credentials.

  3. Click Generate OAuth 2.0 Client Credential.
  4. Enter a Name and Description for this credential..

  5. Add the URI for the OAuth 2.0 services that this credential will provide access to.

    To Select a Resource-Scope Pair
    1. Select the Select a Resource-Scope Pair option.
    2. The Resource list displays the resources you have permission to view. Select the resource you want to add credentials for. After you select the resource, the Audience field is automatically populated.
    3. Next, select the Scope for this credential. Always select the minimum required privileges.
    To Enter Fully Qualified Scope:
    1. Select the Enter Fully Qualified Scope option.
    2. Enter the Audience and Scope for this credential.
  6. To add more permissions to this credential, click + Another Scope and follow the instructions in the previous step.
  7. Click Generate. The new secret string is generated.

    Copy the token string immediately, because you can't retrieve it again after closing the dialog box..

    If you're an administrator creating a Secret Key for another user, you need to securely deliver it to the user.

You will need the following information from the credential for the token request:

  • The generated secret
  • The OCID of the OAuth 2.0 client credential
  • The scope and audience (fully-qualifed scope)
To add scopes to an existing OAuth 2.0 client credential
  1. View the user's details:
    • If you're creating an OAuth 2.0 client credential for yourself:

      Open the Profile menu (User menu icon) and click User Settings.

    • If you're an administrator creating an OAuth 2.0 client credential for another user: In the Console, click Identity, and then click Users. Locate the user in the list, and then click the user's name to view the details.
  2. On the left side of the page, click OAuth 2.0 Client Credentials.

  3. Click the name of the credential that you want to add scopes to.
  4. Click Add Scopes.
  5. Add the URI for the OAuth 2.0 services that you want to add access to.

    To Select a Resource-Scope Pair
    1. Select the Select a Resource-Scope Pair option.
    2. The Resource list displays the resources you have permission to view. Select the resource you want to add credentials for. After you select the resource, the Audience field is automatically populated.
    3. Next, select the Scope for this credential. Always select the minimum required privileges.
    To Enter Fully Qualified Scope:
    1. Select the Enter Fully Qualified Scope option.
    2. Enter the Audience and Scope for this credential.
  6. To add more permissions to this credential, click + Another Scope and follow the instructions in the previous step.
  7. Click Save Changes.
To regenerate the OAuth 2.0 client credential secret

IMPORTANT: When you regenerate the secret for a credential, requests made with the previous secret will be denied access to target scopes.

  1. View the user's details:
    • If you're creating an OAuth 2.0 client credential for yourself:

      Open the Profile menu (User menu icon) and click User Settings.

    • If you're an administrator creating an OAuth 2.0 client credential for another user: In the Console, click Identity, and then click Users. Locate the user in the list, and then click the user's name to view the details.
  2. On the left side of the page, click OAuth 2.0 Client Credentials.

  3. Click the name of the credential that you want to regenerate the secret for.
  4. Click Add Scopes.
  5. Click Regenerate Secret.
  6. Acknowledge the warning dialog and click Regenerate Secret.
  7. Copy the token string immediately, because you can't retrieve it again after closing the dialog box.

Ensure to update existing token requests with the new secret string.

To generate SMTP credentials
  1. View the user's details:
    • If you're generating SMTP credentials for yourself:

      Open the Profile menu (User menu icon) and click User Settings.

    • If you're an administrator generating SMTP credentials for another user: In the Console, click Identity, and then click Users. Locate the user in the list, and then click the user's name to view the details.
  2. Click SMTP Credentials.
  3. Click Generate SMTP Credentials.

  4. Enter a Description of the SMTP Credentials in the dialog box.
  5. Click Generate SMTP Credentials. A user name and password is displayed.
  6. Copy the user name and password for your records and click Close. Copy the credentials immediately, because you can't retrieve the password again after closing the dialog box for security reasons.

    If you're an administrator creating the credential set for another user, you need to securely deliver it to the user by providing it verbally, printing it out, or sending it through a secure email service.

To delete SMTP credentials

The following procedure works for a regular user or an administrator. Administrators can delete SMTP credentials for either another user or themselves.

  1. View the user's details:
    • If you're deleting SMTP credentials for yourself:

      Open the Profile menu (User menu icon) and click User Settings.

    • If you're an administrator deleting SMTP credentials for another user: In the Console, click Identity, and then click Users. Locate the user in the list, and then click the user's name to view the details.
  2. On the left side of the page, click SMTP Credentials.
  3. For the SMTP credentials you want to delete, click Delete.
  4. Confirm when prompted.

The SMTP credentials are no longer available to use with the Email Delivery service.

Using the API

For information about using the API and signing requests, see REST APIs and Security Credentials. For information about SDKs, see Software Development Kits and Command Line Interface.

Use this API operation to manage Console passwords and access:

  • CreateOrResetUIPassword: This generates a new one-time Console password for the user. The next time the user signs in to the Console, they'll be prompted to change the password.
  • UpdateUserState: Unblocks a user who has tried to sign in 10 times in a row unsuccessfully.

Use these API operations to manage API signing keys:

Use these API operations to manage auth tokens:

Use these API operations to manage Customer Secret keys:

Use these API operations to manage OAuth 2.0 client credentials:

Use these API operations to manage SMTP credentials: