7. API: EndUserSecurityContext Class

The EndUserSecurityContext class represents Deep Data Security context information that node-oracledb can set on a connection. It can identify an end user by using an end-user token from an external Identity and Access Management (IAM) system, or by using the name of a local database user. For direct application logon, it can also represent the application identity encoded by the database-access token, without specifying a separate end-user identity.

The security context information can include the database-access token, end-user identity details, data roles, and application-provided attributes used by Oracle Database to authorize access to protected data.

Added in node-oracledb version 7.0.

Note

In this release, Deep Data Security is only supported in node-oracledb Thin mode.

See Deep Data Security.

The EndUserSecurityContext object is created by using:

const security_context = new oracledb.EndUserSecurityContext(options);

The parameters of the EndUserSecurityContext object are:

Table 7.1 EndUserSecurityContext Parameters
Parameter	Data Type	Description
`options`	Object	The `options` parameter contains the properties necessary to define an end-user security context for a connection. See EndUserSecurityContext options Parameters Attributes for information.

The properties of the options parameter are:

Table 7.2 EndUserSecurityContext `options` Parameter Properties
Property	Data Type	Description
`databaseAccessToken`	String	A security token issued by an external Identity and Access Management (IAM) system such as Oracle Cloud Infrastructure (OCI) IAM or Microsoft Entra ID that authorizes an application to access Oracle Database. This property is required and can either be an On-Behalf-Of (OBO) token or a Client Credentials token. An OBO token is obtained from an IAM using the end-user token as an assertion. This access token can only be used when `endUserToken` is specified. A Client Credentials token is obtained from an IAM using the application’s token. This access token can be used when either `endUserToken` or `endUserName` is specified. It can also be used without `endUserToken` or `endUserName` for direct application logon, where the database maps the token to the application identity.
`endUserToken`	String	A token that identifies an end-user managed by an external IAM system. This token is issued by the IAM system after user authentication. This property should not be set when `endUserName` or `key` is specified.
`endUserName`	String	The name of a local database user created in Oracle Database that has the `CREATE END USER SECURITY CONTEXT` database privilege set. This property should not be set when `endUserToken` is specified.
`key`	String	An optional lookup identifier that the database maps to stored context attributes. This property may be specified with `endUserName` and should not be set when `endUserToken` is specified.
`dataRoles`	Array	The names of data roles granted to the application. These data roles are created with a `CREATE DATA ROLE` statement in the database and granted to an application identity created with `CREATE APPLICATION IDENTITY` statement in the database. For external IAM systems, these data roles are mapped to roles managed in your IAM system. For local database users, these data roles can be used to distinguish sessions for the same local user.
`attributes`	Object	Attribute name-value pairs provided by the application for an END USER CONTEXT declared in the database. The name-value pairs for each context must conform to the JSON schema of that END USER CONTEXT. These pairs are associated with fully qualified END USER CONTEXT names, using the format `{schema}.{name}`, where `schema` is the database schema in which the context is declared and `name` is the name of the END USER CONTEXT. The database does not recognize unqualified END USER CONTEXT names. The attribute values can be referenced at runtime by authorization policies, for example in data grant predicates, and application logic.