Using OAuth 2.0

Four types of authentication work flow are available when using OAuth 2.0, token pass-through, client credentials, browser based authentication, or Azure Managed Identity

This authentication mechanism is available for Spark Thrift Server instances instances only. When you use OAuth 2.0 authentication, HTTP is the only Thrift transport protocol available. Client credentials and 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.

Token Pass-through

This authentication mechanism requires a valid OAuth 2.0 access 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. To obtain a new access token, see Using OAuth 2.0.

To configure OAuth 2.0 token pass-though authentication:

  1. Choose one:
    • To access authentication options for a DSN, open the ODBC Data Source Administrator where you created the DSN, then select the DSN, and then click Configure.
    • Or, to access authentication options for a DSN-less connection, open the Simba Spark ODBC Driver Configuration tool.
  2. From the Mechanism drop-down list, select OAuth 2.0.
  3. Click OAuth Options, and then do the following:
    1. From the Authentication Flow drop-down list, select Token Passthrough.
    2. In the Access Token field, type your access token.
    3. To save your settings and close the OAuth Options dialog box, click OK.
  4. To save your settings and close the DSN Setup dialog box or the Driver Configuration tool, click OK.

Example connection string:

Providing a New Access Token

Once an access token expires, you can provide a new access token for the connector.

Note:

When an access token expires, the connector returns a "SQLState 08006" error.

To obtain a new access token:

  1. In the connection string, set the Auth_AccessToken property with a new access token.
  2. Call the SQLSetConnectAttr function with SQL_ATTR_CREDENTIALS (122) as the attribute and the new connection string as the value. The connector will update the current connection string with the new access token.

    Note:

    Calling the SQLGetConnectAttr function with SQL_ATTR_CREDENTIALS (122) returns the entire connection string used during connection.

  3. Call the SQLSetConnectAttr function with SQL_ATTR_REFRESH_CONNECTION (123) as the attribute and SQL_REFRESH_NOW (-1) as the value. This signals the connector to update the access token value.

  4. Retry the previous ODBC API call. After obtaining the new access token, the open connection, statements, and cursors associated with it remain valid for use.

Client Credentials

This authentication mechanism requires SSL to be enabled.

You can use client secret or JWT assertion as the client credentials.

To configure OAuth 2.0 client credentials authentication using the client secret:

  1. Choose one:
    • To access authentication options for a DSN, open the ODBC Data Source Administrator where you created the DSN, then select the DSN, and then click Configure.
    • Or, to access authentication options for a DSN-less connection, open the Simba Spark ODBC Driver Configuration tool.
  2. From the Mechanism drop-down list, select OAuth 2.0.
  3. Click OAuth Options, and then do the following:
    1. From the Authentication Flow drop-down list, select Client Credentials.
    2. In the Client ID field, type your client ID.
    3. In the Client Secret field, type your client secret.
    4. Optionally, select Encryption Options... and choose the encryption password for Current User Only or All Users of this Machine. Then click OK.
    5. Optionally, select the Ignore SQL_DRIVER_NOPROMPT check box. When the application is making a SQLDriverConnect call with a SQL_DRIVER_NOPROMPT flag, this option displays the web browser used to complete the browser based authentication flow.
    6. To save your settings and close the OAuth Options dialog box, click OK.
  4. To save your settings and close the DSN Setup dialog box or the Driver Configuration tool, click OK.

To configure OAuth 2.0 client credentials authentication using the JWT assertion:

  1. Choose one:
    • To access authentication options for a DSN, open the ODBC Data Source Administrator where you created the DSN, then select the DSN, and then click Configure.
    • Or, to access authentication options for a DSN-less connection, open the Simba Spark ODBC Driver Configuration tool.
  2. From the Mechanism drop-down list, select OAuth 2.0.
  3. Click OAuth Options, and then do the following:
    1. From the Authentication Flow drop-down list, select Client Credentials.
    2. Select the Use JWT Assertion check box.
    3. In the Client ID field, type your client ID.
    4. In the JWT Key Identifier field, type your key identifier.
    5. In the JWT Private Key Path field, select your private key pem file.
    6. In the JWT Private Key Password field, type your passphrase, if your private key is encrypted.
    7. Optionally, click JWT Private Key Encryption Options and select the encryption password for Current User Only or All Users of this Machine. Click OK.
    8. In the OIDC Discovery Endpoint field, type your discovery endpoint.
    9. To save your settings and close the OAuth Options dialog box, click OK.
  4. To save your settings and close the DSN Setup dialog box or the Driver Configuration tool, click OK.

Browser Based

This authentication mechanism requires SSL to be enabled.

To configure OAuth 2.0 browser based authentication:

  1. Choose one:
    • To access authentication options for a DSN, open the ODBC Data Source Administrator where you created the DSN, then select the DSN, and then click Configure.
    • Or, to access authentication options for a DSN-less connection, open the SimbaSpark ODBC Driver Configuration tool.
  2. From the Mechanism drop-down list, select OAuth 2.0.
  3. Click OAuth Options, and then do the following:
    1. From the Authentication Flow drop-down list, select Browser Based Authorization Code.
    2. Optionally, select the Ignore SQL_DRIVER_NOPROMPT check box. When the application is making a SQLDriverConnect call with a SQL_DRIVER_NOPROMPT flag, this option displays the web browser used to complete the browser based authentication flow.
    3. To save your settings and close the OAuth Options dialog box, click OK.
  4. To save your settings and close the DSN Setup dialog box or the Driver Configuration tool, click OK.

Note:

When the browser based authentication flow completes, the access token and refresh token are saved in the token cache and the connector does not need to authenticate again. For more information, see Enable Token Cache.

Azure Managed Identity

This authentication mechanism requires SSL to be enabled.

To configure Azure Managed Identity based authentication:

  1. Choose one:
    • To access authentication options for a DSN, open the ODBC Data Source Administrator where you created the DSN, then select the DSN, and then click Configure.
    • Or, to access authentication options for a DSN-less connection, open the SimbaSpark ODBC Driver Configuration tool.
  2. From the Mechanism drop-down list, select OAuth 2.0.
  3. Click OAuth Options, and then do the following:
    1. From the Authentication Flow drop-down list, select Azure Managed Identity.
    2. Optionally, in the Client ID field, type the user-assigned managed identity.
    3. Optionally, in the Azure Workspace Resource ID, type your Resource ID.
    4. To save your settings and close the OAuth Options dialog box, click OK.
  4. To save your settings and close the DSN Setup dialog box or the Driver Configuration tool, click OK.

Related topics