Oracle Cloud Infrastructure Documentation

Authenticating and Authorizing Microsoft Entra ID (MS-EI) Users for Oracle Databases on Oracle Exadata Database Service on Dedicated Infrastructure

An Oracle Database can be configured for Microsoft Azure users of Microsoft Entra ID to connect using single sign-on authentication.

Parent topic: How-to Guides

About Authorizing Microsoft Entra ID (MS-EI) Users for Oracle Databases on Oracle Exadata Database Service on Dedicated Infrastructure

Users for Oracle Exadata Database Service on Dedicated Infrastructure can be centrally managed in an MS-EI service.

The Oracle Database integration with MS-EI is supported for on-premises databases and most Oracle OCI DBaaS platforms.

The instructions for configuring MS-EI use the term "Oracle Database" to encompass these environments.

This type of integration enables the MS-EI user to access an Oracle Exadata Database Service on Dedicated Infrastructure instance. MS-EI users and applications can log in with MS-EI Single Sign On (SSO) credentials to get an MS-EI OAuth2 access token to send to the database.

The administrator creates and configures the application registration (app registration) of the Oracle Exadata Database Service on Dedicated Infrastructure instance with MS-EI. The administrator also creates application (app) roles for the database app registration in MS-EI, and assigns these roles to MS-EI users, groups, and applications. These app roles will be mapped to the database global schemas and global roles. An MS-EI principal that is assigned to an app role will be mapped to either a database global schema or database global role. An Oracle global schema can also be mapped exclusively to an MS-EI user. When the principal is a guest user or service principal, they can only be mapped to the database schema through an MS-EI app role. An Oracle global role can only be mapped to an MS-EI app role.

Tools and applications that are updated to support MS-EI tokens can authenticate users directly with MS-EI and pass the database access token to the Oracle Exadata Database Service on Dedicated Infrastructure instance. You can configure existing database tools such as SQL*Plus to use an MS-EI token from a file location or get the token directly from MS-EI. When using a utility to get the token to pass to the database client driver through a file location, MS-EI tokens can be retrieved using tools like Microsoft PowerShell or Azure CLI and put into a file location. An MS-EI OAuth2 database access token is a bearer token with an expiration time. The Oracle Database client driver will ensure that the token is in a valid format and that it has not expired before passing it to the database. The token is scoped for the database. Assigned app roles for the Azure AD principal are included as part of the access token. The directory location for the MS-EI token should only have enough permission for the user to write the token file to the location and the database client to retrieve these files (for example, just read and write by the process user). Because the token allows access to the database, it should be protected within the file system.

MS-EI users can request a token as a client registered with MS-EI app registration by using methods such as the following:

  • Entering the MS-EI credentials into an MS-EI authentication screen with or without multi-factor authentication

Oracle Exadata Database Service on Dedicated Infrastructure supports the following MS-EI authentication flows:

  • Interactive flow (authorization code), which is used when a browser can be used to enter credentials for the user
  • Client credentials, which are for applications that connect as themselves (and not the end-user)
  • On-Behalf-Of (OBO), where an application requests an access token on behalf of a logged-in user to send to the database
  • ROPC is also supported for test and development environments

Oracle Exadata Database Service on Dedicated Infrastructure accepts tokens representing the following MS-EI principals:

  • MS-EI user, who is registered user in the MS-EI tenancy
  • Guest user, who is registered as a guest user in the MS-EI tenancy
  • Service, which is the registered application connecting to the database as itself with the client credential flow (connection pool use case)

Configuring the Oracle Database for Microsoft Entra ID (MS-EI) Integration

The MS-EI integration with the Oracle Database instance requires the database to be registered with MS-EI so that the database can request the MS-EI public key.

For information on configuring MS-EI, configuring the database, and configuring the database client, see:

Parent topic: Authenticating and Authorizing Microsoft Entra ID (MS-EI) Users for Oracle Databases on Oracle Exadata Database Service on Dedicated Infrastructure

Prerequisites for Microsoft Entra ID (MS-EI) Authentication

Review the prerequisites for integrating Oracle Database with MS-EI.

The MS-EI integration with the Oracle Database on Oracle Exadata Database Service on Dedicated Infrastructure requires:

  1. The Oracle Database to be version 19.18 or higher.
  2. Connectivity to the database on TLS port 2484. Non TLS connections are not supported.
  3. Outbound network connectivity to MS-EI so that the database can request the MS-EI public key.
  4. The Oracle Database to be registered with MS-EI.
  5. Users and applications that need to request an MS-EI token must also be able to have network connectivity to MS-EI. You may need to configure a proxy setting for the connection.
  6. For Oracle Exadata Database Service on Dedicated Infrastructure deployments, the HTTP Proxy settings in your environment must allow the database to use MS-EI.

    These settings are defined by your fleet administrator while creating the Oracle Exadata Database Service on Dedicated Infrastructure infrastructure as described in To create a Cloud Exadata infrastructure resource.

    Note

    The network configuration including the HTTP Proxy can only be edited until the Exadata Infrastructure is in Requires Activation state. Once it is activated, you cannot edit those settings.

    Setting up an HTTP Proxy for an already provisioned Exadata Infrastructure needs a Service Request (SR) in My Oracle Support. See Create a Service Request in My Oracle Support for details.

Networking Prerequisites for Microsoft Entra ID (MS-EI) Authentication

Before using Azure AD authentication on databases in the Exadata Cloud Infrastructure, you must use the Networking service to add a service gateway, a route rule, and an egress security rule to the Virtual Cloud Network (VCN) and subnets where your database resources reside.

  1. Create a service gateway in the VCN where your database resources reside by following the instructions in Task 1: Create the service gateway in OCI documentation.
  2. After creating the service gateway, add a route rule and an egress security rule to each subnet (in the VCN) where the database resources reside so that these resources can use the gateway to use Azure AD authentication:
    1. Go to the Subnet Details page for the subnet.
    2. In the Subnet Information tab, click the name of the subnet's Route Table to display its Route Table Details page.
    3. In the table of existing Route Rules, check whether there is already a rule with the following characteristics:
      • Destination: 0.0.0.0/0
      • Target Type: NAT Gateway
      • Target: The name of the NAT gateway you just created in the VCN

      If such a rule does not exist, click Add Route Rules and add a route rule with these characteristics.

    4. Return to the Subnet Details page for the subnet.
    5. In the subnet's Security Lists table, click the name of the subnet's security list to display its Security List Details page.
    6. In the side menu, under Resources, click Egress Rules.
    7. In the table of existing Egress Rules, check whether there is already a rule with the following characteristics:
      • Destination Type: CIDR
      • Destination: 0.0.0.0/0
      • IP Protocol: TCP
      • Source Port Range: 443
      • Destination Port Range: All
    8. If such a rule does not exist, click Add Egress Rules and add an egress rule with these characteristics.

Configure TLS to Use Microsoft Entra ID (MS-EI) Tokens

When sending MS-EI tokens from the database client to the database server, a TLS connection must be established.

The TLS wallet with the database certificate for the ExaDB-D service instance must be stored under the WALLET_ROOT location. Create a tls directory so it looks like: WALLET_ROOT/<PDB GUID>/tls.

When configuring TLS between the database client and server there are several options to consider.

  • Using a self-signed database server certificate vs a database server certificate signed by a commonly known certificate authority
  • One-way TLS (TLS) vs Mutual or two-way TLS (mTLS)
  • Client with or without a wallet

Self-Signed Certificate

Using a self-signed certificate is a common practice for internally facing IT resources since you can create these yourself and it's free. The resource (in our case, the database server) will have a self-signed certificate to authenticate itself to the database client. The self-signed certificate and root certificate will be stored in the database server wallet. For the database client to be able to recognize the database server certificate, a copy of the root certificate will also be needed on the client. This self-created root certificate can be stored in a client-side wallet or installed in the client system default certificate store (Windows and Linux only). When the session is established, the database client will check to see that the certificate sent over by the database server has been signed by the same root certificate.

A Well-Known Certificate Authority

Using a commonly known root certificate authority has some advantages in that the root certificate is most likely already stored in the client system default certificate store. There is no extra step for the client to store the root certificate if it is a common root certificate. The disadvantage is that this normally has a cost associated with it.

One-Way TLS

In the standard TLS session, only the server provides a certificate to the client to authenticate itself. The client doesn't need to have a separate client certificate to authenticate itself to the server (similar to how HTTPS sessions are established). While the database requires a wallet to store the server certificate, the only thing the client needs to have is the root certificate used to sign the server certificate.

Two-Way TLS (also called Mutual TLS, mTLS)

In mTLS, both the client and server have identity certificates that are presented to each other. In most cases, the same root certificate will have signed both of these certificates so the same root certificate can be used with the database server and client to authenticate the other certificate. mTLS is sometimes used to authenticate the user since the user identity is authenticated by the database server through the certificate. This is not necessary for passing IAM tokens but can be used when passing IAM tokens.

Client with a Wallet

A client wallet is mandatory when using mTLS to store the client certificate. However, the root certificate can be stored either in the same wallet or in the system default certificate store.

A Client without a Wallet

Clients can be configured without a wallet when using TLS under these conditions: 1) One-way TLS is being configured where the client does not have its own certificate and 2) the root certificate that signed the database server certificate is stored in the system default certificate store. The root certificate would most likely already be there if the server certificate is signed by a common certificate authority. If it's a self-signed certificate, then the root certificate would need to be installed in the system default certificate store to avoid using a client wallet.

For details on how to configure TLS between the database client and database server including the options described above, see:

If you choose to use self-signed certificates and for additional wallet related tasks, see: