17.6.1 Understanding Web 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 Oracle APEX components and APIs. 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
  Protect Web credentials by adding valid URLs.
• About Supported Authentication Types in Web Credentials
  Learn about supported authentication types in Web credentials.
• Using a Database Credential with Web Credentials
  Learn about using a database credential with Web credentials.
• Exporting and Importing Web Credentials
  Learn about exporting and importing Web credentials.

See Also:

Managing REST Enabled SQL References

17.6.1.1 Protecting Web Credentials by Defining Valid URLs

Protect Web credentials by adding valid URLs.

You can optionally protect Web credentials by adding valid URLs to the Valid for URLs attribute. Adding URLs to the Valid for URLs attribute prevents APEX from accidentally sending sensitive credentials to a different server. Whenever a Web credential is used, APEX checks whether the URL matches what is defined in the Valid for URLs attribute. If the URL does not match, APEX raises the runtime error, Credential is not allowed to be used for this URL endpoint.

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.

17.6.1.2 About Supported Authentication Types in Web Credentials

Learn about supported authentication types in Web credentials.

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 - APEX 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, APEX 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. APEX 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. APEX 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.

17.6.1.3 Using a Database Credential with Web Credentials

Learn about using a database credential with Web credentials.

Note:

This feature is only available on Oracle Database release 23c or Autonomous Database release 19c or later.

For Oracle Database 23c or Autonomous Database 19c or later, Web credentials can reference a database credential to store the Client ID and Client Secret when the Web credential is of the Basic Authentication or OAuth2 Client Credentials type. Other Web credential types do not support database credentials.

Using a database credential changes the behavior of HTTP requests being done and how Web credentials work:

• If a database credential is used, all HTTP requests are done in the context of the application's parsing schema and not in the context of the APEX engine. Therefore, the PL/SQL network ACLs must be granted to the application's parsing schema. To learn more, DBMS_NETWORK_ACL_ADMIN in Oracle Database PL/SQL Packages and Types Reference.
• A database credential is completely maintained by the database, Oracle APEX does not have access to the stored secrets. Since APEX cannot enforce the Valid for URLs attribute, this attribute is disabled when a database credential is used.

Tip:

You can maintain a database credential using the DBMS_CREDENTIAL or DBMS_CLOUD packages.

About Instance and Schema Database Credentials

If a Web credential references a database credential, the database credential must be accessible to the application's parsing schema. If the INSTANCE_DBMS_CREDENTIAL_ENABLED instance parameter is enabled (set to the 'Y' value), then a database credential, which is accessible to the APEX engine schema (APEX_NNNNNN) can be used in all workspaces.

See Also:

INSTANCE_DBMS_CREDENTIAL_ENABLED in Available Parameter Values, APEX_INSTANCE_ADMIN in Oracle APEX API Reference

17.6.1.4 Exporting and Importing Web Credentials

Learn about exporting and importing Web credentials.

When you export an application, used credentials are added to the export file. When you import the application into another workspace, APEX 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.