17.6 Managing Web Credentials

Store authentication credentials for external REST services or REST Enabled SQL services.

• About Credentials
  Use Web credentials to connect to external REST services or REST Enabled SQL services.
• Creating Web Credentials
  Create Web credentials from either Workspace Utilities or Shared Components.
• Editing or Deleting Credentials
  Edit or delete Web credentials from either Workspace Utilities or Shared Components.
• Viewing Credential Utilization
  View the Web credential Utilization report.
• Viewing Credential History
  View the Web credential History report.

17.6.1 About Credentials

Use Web credentials to connect to external REST services or REST Enabled SQL services.

Creating Web credentials securely stores and encrypts authentication credentials for use by Application Express components and API's. Credentials cannot be retrieved back in clear text. Credentials are stored at the workspace-level and therefore are visible in all applications.

Protecting Web Credentials by Defining Valid URLs

You can protect Web credentials by adding valid URLs to the Valid for URLs attribute. Adding URLs to the Valid for URLs attribute prevents Application Express from accidentally sending a sensitive credentials to a different server. Whenever a Web credentials is used, Application Express checks whether the URL matches what is defined in defined in the Valid for URLs attribute.

When adding URLs to this attribute, place each URL into a new line. The URL endpoint being used must start with one of the URLs provided here. See field-level Help for examples.

Exporting and Importing Credentials

When you export an application, used credentials are added to the export file. When you import the application into another workspace, Application Express checks whether the target workspace already contains credentials with the same static ID. If a credential already exists, the application uses it. Otherwise the credential from the import file is created in the target workspace.

About Supported Authentication Types

Web credentials support the following Authentication Types:

• Basic Authentication - Sends username and password in Base64-encoded form as the Authorization request header.

• OAuth2 Client Credentials Flow - Application Express exchanges the client ID and client secret for an Access Token using a token server URL. The access token is then used to perform the actual request. If the access token is expired, Application Express will transparently request a new one.

• HTTP Header - The credential is added to the REST Request as a HTTP Header. The name of the credential is the HTTP Header name, the Secret of the credential is the HTTP Header value. Application Express does not add these secrets to the Debug log or any other logs.

• URL Query String - The credential is added to the URL of the REST Request as a Query String Parameter (for example: ?name=value). This option can be useful with API keys. Application Express does not add these secrets to the Debug log or any other logs. However,proxy or other intermediate servers will log these credentials in their log files.

See Also:

"Managing REST Enabled SQL References"

17.6.2 Creating Web Credentials

Create Web credentials from either Workspace Utilities or Shared Components.

To create Web credentials:

1. Navigate to the Web Credentials page:
   • From Workspace Utilities:

     1. On the Workspace home page, click App Builder.

     2. Click Workspace Utilities.

     3. Click Web Credentials.

   • From Shared Components:

     1. On the Workspace home page, click App Builder.

     2. Select an application.

     3. On the Application home page, click Shared Components in the center of the page.

     4. Under Security, select Web Credentials.

2. On the Web Credentials page, click Create.
3. Configure the Attributes on the Web Credentials page.
4. Name - Enter a descriptive name.
5. Authentication Type - Select one of the following:
   • Basic Authentication
   • OAuth2 Client Credentials Flow
   • HTTP Header
   • URL Query String

   To learn more about this attribute, see field level Help.

   The options that display next depends upon the Authentication Type you select.

6. For the Authentication Type, Basic Authentication:
   1. Client ID or User Name - Enter the Username. Application Express does not store this information encrypted.
   2. Client Secret or Password - Enter the password.
   3. Verify Client Secret or Password - Enter the password again to verify your input.
   4. Valid for URLs - Application Express checks whether the URL a Web credentials uses matches the URLs in this attribute. When adding URLs to this attribute:

      • Place each URL on a new line.

      • The URL endpoint being used must start with one of the URLs provided here.

      See field-level Help for examples.

   5. Prompt On Install - Choose whether prompts for this credential display when the application is imported on another Oracle Application Express instance.
   6. Comments - Enter any comments or notes here. These comments never display when running the application.
7. For the Authentication Type, OAuth2 Client Credentials Flow:
   1. OAuth Scope - Permissions represented by the Access Token in OAuth 2.0 terms are known as scopes. The scope parameter allows the application to express the desired scope of the access request.

      If your authentication server requires a scope to be specified for the access token request, provide it here. The OAuth2 access token will then be requested with the following request body:

      grant_type=client_credentials&scope={scope}

   2. Client ID or User Name - Enter the Client ID. Application Express does not store this information encrypted.
   3. Client Secret or Password - Enter the Secret again, to verify your input.
   4. Valid for URLs - Application Express checks whether the URL a Web credentials uses matches the URLs in this attribute. When adding URLs to this attribute:

      • Place each URL on a new line.

      • The URL endpoint being used must start with one of the URLs provided here.

      See field-level Help for examples.

   5. Prompt On Install - Choose whether prompts for this credential display when the application is imported on another Oracle Application Express instance.
   6. Comments - Enter any comments or notes here. These comments never display when running the application.
8. For the Authentication Type, HTTP Header:
   1. Credential Name - Enter the name of the HTTP Header to use for this credential.
   2. Credential Secret - Enter the value (or secret) of the credential.
   3. Valid for URLs - Application Express checks whether the URL a Web credentials uses matches the URLs in this attribute. When adding URLs to this attribute:

      • Place each URL on a new line.

      • The URL endpoint being used must start with one of the URLs provided here.

      See field-level Help for examples.

   4. Prompt On Install - Choose whether prompts for this credential display when the application is imported on another Oracle Application Express instance.
   5. Comments - Enter any comments or notes here. These comments never display when running the application.
9. For the Authentication Type, URL Query String:
   1. Credential Name - Enter the name of the URL Query String parameter to use for this credential.
   2. Credential Secret - Enter the value (or secret) of the credential.
   3. Valid for URLs - Application Express checks whether the URL a Web credentials uses matches the URLs in this attribute. When adding URLs to this attribute:

      • Place each URL on a new line.

      • The URL endpoint being used must start with one of the URLs provided here.

      See field-level Help for examples.

   4. Prompt On Install - Choose whether prompts for this credential display when the application is imported on another Oracle Application Express instance.
   5. Comments - Enter any comments or notes here. These comments never display when running the application.
10. Click Apply Changes.

17.6.3 Editing or Deleting Credentials

Edit or delete Web credentials from either Workspace Utilities or Shared Components.

To Edit or delete Web credentials:

1. Navigate to the Web Credentials page:
   • From Workspace Utilities:

     1. On the Workspace home page, click App Builder.

     2. Click Workspace Utilities.

     3. Click Web Credentials.

   • From Shared Components:

     1. On the Workspace home page, click App Builder.

     2. Select an application.

     3. On the Application home page, click Shared Components in the center of the page.

     4. Under Security, select Web Credentials.

2. On the Web Credentials page, select the credential name.
   The Create/Edit page appears.
3. To edit a credential:
   1. Edit the appropriate attributes. To learn more about an attribute, see field level Help.
   2. To save your changes, click Apply Changes.
4. To delete a credential:
   1. To delete a credential, click Delete.
   2. When prompted, click OK.

      Tip:

      A credential cannot be deleted when it is being referenced somewhere in the workspace.

17.6.4 Viewing Credential Utilization

View the Web credential Utilization report.

To view Web credential Utilization report:

1. Navigate to the Web Credentials page:
   • From Workspace Utilities:

     1. On the Workspace home page, click App Builder.

     2. Click Workspace Utilities.

     3. Click Web Credentials.

   • From Shared Components:

     1. On the Workspace home page, click App Builder.

     2. Select an application.

     3. On the Application home page, click Shared Components in the center of the page.

     4. Under Security, select Web Credentials.

2. On the Web Credentials page, click Utilization.
   The top of the Utilization page displays used credentials, the associated component type, and the component name. Unused credentials display at the bottom of the page.
3. To delete unused credentials, click Delete Unused.

17.6.5 Viewing Credential History

View the Web credential History report.

To view Web credential History report:

1. Navigate to the Web Credentials page:
   • From Workspace Utilities:

     1. On the Workspace home page, click App Builder.

     2. Click Workspace Utilities.

     3. Click Web Credentials.

   • From Shared Components:

     1. On the Workspace home page, click App Builder.

     2. Select an application.

     3. On the Application home page, click Shared Components in the center of the page.

     4. Under Security, select Web Credentials.

2. On the Web Credentials page, click History.
   The History page displays recent modifications made to Credentials in the current workspace.