Using OAuth 2.0

Four types of authentication work flows are available when using OAuth 2.0: token pass-through, browser based, M2M , and Azure Managed Identity.

This authentication mechanism is available for Spark Thrift Server instances only. When you use OAuth 2.0 authentication, HTTP is the only Thrift transport protocol available. Browser based authentication work flow only works when SSL is enabled.

There is a discovery mode that enables the connector to auto-fill some endpoints or configurations. The endpoint discovery is enabled by default, you can disable it by setting EnableOIDCDiscovery=0. You can also pass the OIDC discovery endpoint by using OIDCDiscoveryEndpoint. The connector automatically discovers OAuth2AuthorizationEndPoint and OAuth2TokenEndPoint.

To enable SSL for OAuth endpoints, UseServerSSLConfigsForOAuthEndPoint can be used.

Token Pass-through

This authentication mechanism requires a valid OAuth 2.0 access token or refresh token. Be aware that access tokens typically expire after a certain amount of time, after which you must either refresh the token or obtain a new one from the server. If refresh token is provided, then the connector would use it to refresh access token when necessary.

Note:

When the access token expires, the connector will return an error with SQLState 08006. To provide the connector with a new access token, use Connection.setClientInfo() with "Auth_AccessToken" as the key and the new access token as the value. The connector will update the access token and use the newly provided token for any subsequent calls to the server.

For more information regarding Connection.setClientInfo() please refer to https://docs.oracle.com/javase/8/docs/api/java/sql/Connection.html#setClientInfo-java.lang.String-java.lang.String-.

To configure OAuth 2.0 token pass-through using Access token in authentication :

  1. Set the AuthMech property to 11.
  2. Set the Auth_Flow property to 0.
  3. Set the Auth_AccessToken property to your access token.

To configure OAuth 2.0 token pass-through using Refresh token in authentication:

  1. Set the AuthMech property to 11.
  2. Set the Auth_Flow property to 0.
  3. Set the Auth_RefreshToken property to your refresh token.

    Note: OAuth2ClientId and OAuth2Secret are optional. If no client ID is provided, the connector will use the default client ID.

Using Browser Based Authentication

This authentication mechanism requires SSL to be enabled.

To configure OAuth 2.0 browser based authentication:

  1. Set the AuthMech property to 11.
  2. Set the Auth_Flow property to 2.
  3. Set the PWD property to a password of your choice. This is the key used for refresh token encryption.

Once the browser based authentication flow is done, the refresh token is cached so you don't need to do authenticate again. The token cache can be disabled by setting EnableTokenCache=0. The TokenCachePassPhrase property needs to be set when using the token cache.

Using M2M Based Authentication

This authentication mechanism is available for Spark Thrift Server instances only.

To configure OAuth 2.0 M2M based authentication:

  1. Set the AuthMech property to 11.
  2. Set the Auth_Flow property to 1.
  3. Set the OAuth2ClientId property to client id used in specified authentication source.
  4. Set the OAuth2Secret property to secret used in the specified authentication source.

To configure JWT assertion authentication:

  1. Set the Auth_KID property to unique key ID.
  2. Set the Auth_JWT_Key_File property to key PEM file.
  3. Set the Auth_JWT_Key_Passphrase property, if private key needs to be decrypted, otherwise keep setting unset.
  4. Set the UseJWTAssertion property to 1.
  5. Set the Auth_JWT_Alg property to use an alternate signing algorithm: RS256, RS384, RS512, PS256, PS384, PS512, ES256, ES384, ES512.
Note:

For JWT assertion authentication, import BouncyCastle v1.74.

Using Azure Managed Identity Authentication

To configure Azure Managed Identity authentication:

  1. Set the AuthMech property to 11.
  2. Set the Auth_Flow property to 3.
  3. Optionally, set the OAuth2ClientId property to client id used in user-assigned managed identity.
  4. Optionally, set the Azure_workspace_resource_id, if your resource is a contributor.