Create Application Identity

Use the CREATE APPLICATION IDENTITY command to register an application as an identity in the database. After creation, you can grant data roles (that are managed locally in the database) to the application identity so that all sessions associated with that application can enable those roles.

Required privilege

The CREATE APPLICATION IDENTITY system privilege.

Syntax

CREATE [ OR REPLACE ] APPLICATION IDENTITY
  [ IF NOT EXISTS ] app_identity
  MAPPED TO 'identifier_string';

Parameters

Parameter	Description
app_identity	The name of the application identity to be created.
identifier_string	The identifier string for the external identity provider mapping. Supported prefixes are: AZURE_CLIENT_ID=<id> for Microsoft Entra ID, IAM_OAUTH_CLIENT_ID=<id> for Oracle Cloud Infrastructure Identity and Access Management (OCI IAM), and CLIENT_ID=<id> for the configurable OAuth 2.0 provider. For the configurable OAuth 2.0 provider, <id> is the value of the claim specified by application_id_claim in the database-access token. The identifier_string parameter must be fewer than 1024 characters. The database raises ORA-28303 if this limit is exceeded.

Usage notes and restrictions

• When OR REPLACE is specified:

  • If the application identity already exists, the identifier_string is replaced.

  • If the application identity does not exist, it is created.

• When OR REPLACE is omitted:

  • If the application identity already exists, an error is raised.

  • If the application identity does not exist, it is created.

• When IF NOT EXISTS is specified:

  • If the application identity already exists, the statement is a no-op. No error is raised.

  • If the application identity does not exist, it is created.

• When IF NOT EXISTS is omitted:

  • If the application identity already exists, an error is raised.

  • If the application identity does not exist, it is created.

• OR REPLACE and IF NOT EXISTS are mutually exclusive in the same statement. Using both raises the ORA-11541 error.

• Each application identity must have a unique identifier string. Creating a new identity with an identifier string already belonging to another application identity raises an error. The identifier string comparison is case-insensitive.

• The same application cannot have more than one application identity mapping in the database.

For syntax diagrams and additional details, see CREATE APPLICATION IDENTITY in Oracle AI Database SQL Language Reference.

Example: Create an application identity using Microsoft Entra ID

Create an application identity for an HCM application using the appid (v1 tokens) or azp (v2 tokens) claim from the Entra ID token.

CREATE APPLICATION IDENTITY hcm_app
  MAPPED TO 'AZURE_CLIENT_ID=2edc9c9f-8e1e-4ade-8a4a-cc286ed1b899';

Example: Create an application identity using OCI IAM

Create an application identity for an HCM application using the client_id claim from the OCI IAM token.

CREATE APPLICATION IDENTITY hcm_app
  MAPPED TO 'IAM_OAUTH_CLIENT_ID=e83a43ac80d94637bb1958b06929ac32';

Example: Create an application identity using Keycloak

Create a database application identity for ORDS. In this example, ORDS’s database-access token contains client_id set to ords_client. Set application_id_claim to client_id in the database identity provider configuration.

CREATE APPLICATION IDENTITY hcm_app
  MAPPED TO 'CLIENT_ID=ords_client';

The client identifier can differ from the token’s subject (sub).

Example: Grant data role to application identity

Grant a data role hcm_role that is managed locally to the application identity, so the HCM application can enable it during its sessions for all application users.

GRANT DATA ROLE hcm_role TO hcm_app;