Using OAuth 2.0

Three types of authentication work flow are available when using OAuth 2.0, token pass-through, client credentials, or browser based authentication.

When you use OAuth 2.0 authentication, HTTP is the only transport mode protocol available.

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. 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
  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. Optionally, select Token or Client Secret Encryption Options and choose the encryption password for Current User Only or All Users of this Machine. Click OK.
    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.

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 as the client credentials.

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

  1. 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.
  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. In the Audience field, type your OAuth audience.
    5. In the Token Endpoint field, type your OAuth token endpoint.
    6. Optionally, select Token or Client Secret Encryption Options and choose the encryption password for Current User Only or All Users of this Machine. Click OK.
    7. Optionally, in the Scope field, type your OAuth scope.
    8. 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. 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.
  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. In the Client ID field, type your client ID.
    3. In the Client Secret field, type your client secret.
    4. Optionally, select Token or Client Secret Encryption Options and choose the encryption password for Current User Only or All Users of this Machine. Click OK.
    5. In the Audience field, type your OAuth audience.
    6. In the Token Endpoint field, type your OAuth token endpoint.
    7. In the Authorization Endpoint field, type your OAuth authorization endpoint.
    8. Optionally, in the Scope field, type your OAuth scope.
    9. 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.
    10. 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.