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.

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.

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 Base64-encoded username and password, as the Authorization request header.
OAuth2 Client Credentials - Exchanges 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.
OCI Native Authentication - Signs requests to the Oracle Cloud Infrastructure (OCI) REST API, as described in Request Signatures.
HTTP Header - Adds credentials to the REST request as a HTTP request 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.
OAuth2 Password Flow - Exchanges client ID, client secret, username and password 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. The OAuth2 Password flow credential stores the client ID and client secret. The username and password are stored in a second credential, the Basic Authentication Credential.
Signed User Assertion - Similar to OAuth2 Client Credentials, but the current user’s identity is additionally asserted using a signed JSON Web Token (JWT). In order to use this authentication type, the OAuth client must be configured in the Identity Provider as Trusted.
User Assertion Signing Certificate - Used in combination with Signed User Assertion and contains a public certificate and private key which will be used to sign User Assertion JWTs. The public certificate must be registered with the Trusted OAuth client in the Identity Provider.
Key Pair - Contains a pair of public and private keys.
Certificate Pair - Used in combination with SAML authentication, and contains a pair of public certificate key and private key. Only available when SAML is enabled for the Oracle APEX instance.

Note: If the token server issued a Refresh Token, that refresh token will be used to refresh an expired access token.

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 26ai or Autonomous Database release 19c or later.

For Oracle Database 26ai or Autonomous Database 19c or later, Web credentials can reference a database credential to store the details when the Web credential is of the Basic Authentication, OAuth2 Client Credentials, or OCI Native Authentication type. Database Credentials can also be used for Signed User Assertion credentials. Other Web credential types do not support database credentials.

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

If a database credential is used, all HTTP requests are made 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, see DBMS_NETWORK_ACL_ADMIN in Oracle AI 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

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.