Troubleshooting Microsoft Entra ID Connections

You can use trace files to diagnose problems with Microsoft Entra ID connections. You also can easily remedy ORA-12599 and ORA-03114 errors.

• Trace Files for Troubleshooting Oracle Database Client Connections with Entra ID
  You can use trace files to troubleshoot the Oracle Database integration with Entra ID.

• ORA-12599 and ORA-03114 Errors Caused When Trying to Access a Database Using a Token
  The ORA-12599: TNS: cryptographic checksum mismatch and ORA-03114: not connected to ORACLE errors indicate that the database to which you are trying to connect is protected by native network encryption.

• Checking the Entra ID Access Token Version
  You can check the version of the Entra ID access token that your site uses by using the JSON Web Tokens web site.

Trace Files for Troubleshooting Oracle Database Client Connections with Entra ID

You can use trace files to troubleshoot the Oracle Database integration with Entra ID.

• About Trace Files Used for Troubleshooting Connections
  You can generate two levels of trace files to troubleshoot Entra ID connections on client side.

• Setting Client Tracing for Token Authentication
  You can add EVENT settings to the client-side sqlnet.ora file to control client tracing.

About Trace Files Used for Troubleshooting Connections

You can generate two levels of trace files to troubleshoot Entra ID connections on client side.

The two levels of trace files that you can generate are as follows:

• Low level tracing prints traces in case of failures:

  • If TCPS is not set up for the Entra ID connection, then it prints a message that the protocol has to be TCPS.

  • If TLS_SERVER_DN_MATCH is not set to TRUE, then it prints a message that the value is FALSE.

  • If TOKEN_LOCATION has not been specified, then it prints a message that the token location does not exist.

  • If the token is not present at the specified TOKEN_LOCATION, then it prints a message.

  • If the application has passed in the token without setting OCI_ATTR_TOKEN_ISBEARER to true, it prints a message for the missing attribute.

  • If the application has set OCI_ATTR_TOKEN_ISBEARER to TRUE and not passed in the token, it prints a message for the missing attribute.

  • If the token has expired, then it prints a message.

  • If the token is a Microsoft Entra ID v2.0 token and it does not contain upn claim or roles claim, then it prints out a message that the needed claim is missing.

Note: To bring Oracle parameters in accord with the actual encryption and authentication methods for network connections, Oracle is deprecating all connect parameters prefixed with SSL_ in favor of parameters prefixed with TLS_. During this deprecation period, if both TLS_SERVER_DN_MATCH and SSL_SERVER_DN_MATCH parameters are configured, then the SSL_SERVER_DN_MATCH parameter is ignored.

• High level tracing prints traces in case of failure as mentioned above. In addition, it prints traces in case of success, as follows:

  • It prints where TLS_SERVER_DN_MATCH is present, tnsnames.ora or sqlnet.ora. It also prints the value as TRUE if set to TRUE.

  • If both the token and OCI_ATTR_TOKEN_ISBEARER=true are set by the application, then it prints a message.

  • If TOKEN_AUTH has the correct value OAUTH, then it prints the value.

  • If the token is not expired, then it prints a message.

  • If the token is a Microsoft Entra ID v2.0 token and the upn claim or roles claim exist, then it prints out a message that the needed claim exists.

Setting Client Tracing for Token Authentication

You can add EVENT settings to the client-side sqlnet.ora file to control client tracing.

These EVENT settings can be used for both IAM and Entra ID connections with Oracle Database.

Use either of the following methods:

• Add the following settings to the client side sqlnet.ora file:

  • EVENT_25701=14 for low level tracing

  • EVENT_25701=15 for high level tracing

• Set the environment variable EVENT_25701:

  • EVENT_25701=14 for low level tracing

  • EVENT_25701=15 for high level tracing

Client trace files are created in the following locations:

• Linux: $ORACLE_HOME/log/diag/clients

• Windows: %ORACLE_HOME%\log\diag\clients

You can use the ADR_BASE parameter in the client side sqlnet.ora to specify the directory in which tracing messages are stored. Ensure that the directory path is valid and has write permissions. Ensure that the DIAG_ADR_ENABLED parameter is not set to FALSE.

An example of setting ADR_BASE is as follows:

ADR_BASE=/oracle/oauth2/trace

ORA-12599 and ORA-03114 Errors Caused When Trying to Access a Database Using a Token

The ORA-12599: TNS: cryptographic checksum mismatch and ORA-03114: not connected to ORACLE errors indicate that the database to which you are trying to connect is protected by native network encryption.

When tokens are being used to access an Oracle database, a Transport Layer Security (TLS) connection must be established, not network native encryption. To remedy these errors, ensure that TLS is properly configured for your database. You should test the configuration with a local database user name and password and check the following SYSCONTEXT USERENV parameters:

• NETWORK_PROTOCOL

• TLS_VERSION

Related Topics

• Configuring PKI Certificate Authentication

Checking the Entra ID Access Token Version

You can check the version of the Entra ID access token that your site uses by using the JSON Web Tokens web site.

By default, Entra ID v1 access token, but your site may have chosen to use v2. Oracle Database supports v1 tokens and Autonomous Database Serverless supports v2 tokens, as well. If you want to use the v2 access tokens, then you can enable their use for the Oracle database. To find the version of the Entra ID access token that you are using, you can either check with your Entra ID administrator, or confirm the version from the JSON Web Tokens website, as follows.

1. Go to the JSON Web Tokens website.

   https://jwt.io/

2. Copy and paste the token string into the Encoded field.

3. Check the Decoded field, which displays information about the token string.

   Near or at the bottom of the field, you will see a claim entitled ver, which indicates either of the following versions:

   • "ver": "1.0"

   • "ver": "2.0"

Related Topics

• Enabling Microsoft Entra ID v2 Access Tokens