This section shows how to use the driver to authenticate to any data source that supports OAuth.

OAuth requires the authenticating user to interact with REST using the browser. The driver facilitates this in various ways as described in the following sections.

Before following the procedures below, you need to register an OAuth app with the service to obtain the OAuthClientId and OAuthClientSecret.

Desktop Applications

After setting the following connection properties, you are ready to connect:

• OAuthVersion: Set this to the OAuth Version, either 1.0 or 2.0.
• OAuthRequestTokenURL: Required for OAuth 1.0. In OAuth 1.0 this is the URL where the app makes a request for the request token.
• OAuthAuthorizationURL: Required for OAuth 1.0 and 2.0. This is the URL where the user logs into the service and grants permissions to the application. In OAuth 1.0 if permissions are granted the request token is authorized.
• OAuthAccessTokenURL: Required for OAuth 1.0 and 2.0. This is the URL where the request for the access token is made. In OAuth 1.0 the authorized request token is exchanged for the access token.
• OAuthRefreshTokenURL: Required for OAuth 2.0. In OAuth 2.0 this is the URL where the refresh token is exchanged for a new access token when the old one expires. Note that for your data source this may be the same as the access token URL.
• OAuthClientId: Set this to the client Id in your app settings. This is also called the consumer key.
• OAuthClientSecret: Set this to the client secret in your app settings. This is also called the consumer secret.
• CallbackURL: Set this to http://localhost:33333. If you specified a redirect URL in your app settings, this must match.
• InitiateOAuth: Set this to GETANDREFRESH. You can use InitiateOAuth to avoid repeating the OAuth exchange and manually setting the access token in the connection string.

When you connect, the driver opens the OAuth endpoint in your default browser. Log in and grant permissions to the application. The driver then completes the OAuth process:

1. Extracts the access token from the callback URL and authenticates requests.
2. Refreshes the access token when it expires.
3. Saves OAuth values in OAuthSettingsLocation to be persisted across connections.

Web Application

When connecting via a Web application, or if the driver is not authorized to open a browser window, use the provided stored procedures to get and manage the OAuth token values.

Note: You can extend the stored procedure schemas to set defaults for the OAuth URLs or other connection string properties. See Operations for a guide.

Set Up the OAuth Flow

Provide the OAuth URLs to authenticate in the Web flow.

• OAuthRequestTokenURL: Required for OAuth 1.0. In OAuth 1.0 this is the URL where the app makes a request for the request token.
• OAuthAuthorizationURL: Required for OAuth 1.0 and 2.0. This is the URL where the user logs into the service and grants permissions to the application. In OAuth 1.0 if permissions are granted the request token is authorized.
• OAuthAccessTokenURL: Required for OAuth 1.0 and 2.0. This is the URL where the request for the access token is made. In OAuth 1.0 the authorized request token is exchanged for the access token.
• OAuthRefreshTokenURL: Required for OAuth 2.0. In OAuth 2.0 this is the URL where the refresh token is exchanged for a new access token when the old one expires. Note that for your data source this may be the same as the access token URL.

Get an Access Token

In addition to the OAuth URLs, set the following additional connection properties to obtain the OAuthAccessToken:

• OAuthClientId: Set this to the client Id in your app settings. This is also called the consumer key.
• OAuthClientSecret: Set this to the client secret in your app settings. This is also called the consumer secret.
• OAuthVersion: Set this to the OAuth version, either 1.0 or 2.0.

You can then call stored procedures to complete the OAuth exchange:

1. Call the GetOAuthAuthorizationURL stored procedure. Set the AuthMode input to WEB and set the CallbackURL input to the Redirect URI you specified in your app settings. The stored procedure returns the URL to the OAuth endpoint.
2. Log in and authorize the application. You are redirected back to the callback URL.

3. Call the GetOAuthAccessToken stored procedure. Set the AuthMode input to WEB.

   In OAuth 1.0, set the Verifier input to the "oauth_verifier" parameter. Extract the verifier code from the callback URL. Additionally, set the AuthToken and AuthSecret to the values returned by GetOAuthAccessToken.

   In OAuth 2.0, set the Verifier input to the "code" parameter in the query string of the callback URL.

Connect to Data and Refresh the Token

The OAuthAccessToken returned by GetOAuthAccessToken has a limited lifetime. To automatically refresh the token, set the following on the first data connection. Alternatively, use the RefreshOAuthAccessToken stored procedure to manually refresh the token.

OAuth Endpoints

• OAuthRequestTokenURL
• OAuthAuthorizationURL
• OAuthAccessTokenURL
• OAuthRefreshTokenURL

OAuth Tokens and Keys

• OAuthClientId
• OAuthClientSecret
• OAuthRefreshToken
• OAuthAccessToken

Initiate OAuth

• OAuthVersion: Set this to 1.0 or 2.0.
• InitiateOAuth: Set this to REFRESH. You can use InitiateOAuth to avoid repeating the OAuth exchange and manually setting the OAuthAccessToken.
• OAuthSettingsLocation: Set this to the path where the driver will save the OAuth values, to be persisted across connections.

On subsequent data connections, set the following:

• InitiateOAuth
• OAuthSettingsLocation
• OAuthRequestTokenURL
• OAuthAuthorizationURL
• OAuthAccessTokenURL
• OAuthRefreshTokenURL

JWT

The driver supports using JWT as an authorization grant in situations where a user cannot perform an interactive sign-on. After setting the following connection properties, you are ready to connect:

• OAuthVersion: Set this to 2.0
• OAuthAccessTokenURL: Set this to the URL where the JWT is exchanged for an access token.
• OAuthJWTCert: Set this to the certificate you want to use. In most cases this will be a path to a PEM or PFX file.
• OAuthJWTCertType: Set this to the correct certificate type. In most cases this will either PEMKEY_FILE or PFXFILE.
• OAuthJWTCertPassword: If the certificate is encrypted, set this to the encryption password.
• OAuthJWTIssuer: Set this to the issuer. This corresponds to the iss field in the JWT.
• InitiateOAuth: Set this to GETANDREFRESH.

Note that the JWT signature algorithm cannot be set directly. Only the RS256 algorithm is supported.

The driver will then construct a JWT including following fields, and submit it to OAuthAccessTokenURL for an access token.

• scope This will come from Scope if it is provided.
• aud This will come from OAuthJWTAudience if it is provided.
• iss This will come from OAuthJWTIssuer.
• iat This is the time when the JWT is generated.
• exp This is the value of iat plus the value of OAuthJWTValidityTime.
• sub This will come from OAuthJWTSubject if it is provided.