The authorization code grant is a commonly used authorization flow for web and native applications. It provides secure connections by requiring multiple points of authentication before permitting access to data. When using the authorization code flow, the application first navigates to the location hosting the temporary authorization code and retrieves it. Next, the authorization code is exchanged for an access token from the location specified in the TokenURI property. If authentication takes place with a third-party authentication service, the application is redirected to the endpoint provided in the RedirectURI property to begin the session.

To use an authorization code grant:

  • The application should be configured to set the OAuthCode property to specify the authorization code that is exchanged for the access token.
  • Configure the minimum properties required for a connection:
    • If you are using a Model file, set the Config property to provide the name and location of the Model file. For example, C:/path/to/box.rest.
    • If you are using the Sample property, set the Sample property to specify the endpoint that the want to connect to and sample. For example, https://example.com/countries/.
  • Set the AuthenticationMethod property to OAuth2-AuthorizationCode.
    Note: To support existing configurations, the AuthenticationMethod property will continue to support the OAuth2 value for the authorization code grant.
  • Set the ClientID property to specify the client ID key for your application.
  • Set the TokenURI property to specify the endpoint used to exchange authentication credentials for access tokens.
    Note: By default, the connector prefixes the token URI endpoint with a GET request method. However, some OAuth implementations require that the token URI endpoint be passed with a POST request method. In this scenario, the token URI endpoint must be prefixed with POST when specifying the value of the TokenURI property. For example: TokenURI=POST https://example.com/oauth2/authorize/.
  • If required by your authentication flow, set the ClientSecret to specify client secret for your application.
  • If required by your authentication flow, set the RedirectURI to specify the endpoint that the client is returned to after authenticating with a third-party service.
  • Optionally, specify values for a custom HTTP header to be used for authentication, such as those used in tenant ID authentication:
    • Set the AuthHeader property to specify the name of the HTTP header used for authentication.
    • Set the SecurityToken property to specify the value of the HTTP header named by the AuthHeader option.

    For example, if you have the header Authorization:1a2bc34def567, you would specify AuthHeader=Authorization and SecurityToken=1a2bc34def567.

  • Optionally, set the Scope property to specify a space-separated list of OAuth scopes to limit the permissions granted by the access token.
  • Optionally, set the ClientCredentialsMode property to determine how client credentials are sent in a request in a request to obtain an access token. Configure this property for flows that require client credentials to be specified in only a basic authentication header or only as a URL parameter.
    • If set to Default, the client credentials are sent as both a basic authentication header. This is the default setting.
    • If set to Basic, the client credentials are sent as a basic authentication header.
    • If set to Url, the client credentials are sent as a URL parameter.
    • If set to Post, the client credentials are sent in the body of a POST request.

The following example demonstrates a basic session for a Box™ account using an authorization code grant:

Using a connection URL: 

Connection conn = DriverManager.getConnection
  ("jdbc:datadirect:autorest:AuthenticationMethod=OAuth2-AuthorizationCode;
    ClientID='abcdefghik2lmn3o5qr67s';Config=C:/path/to/box.rest;
    OAuthCode='xyz123abc';TokenURI='https://api.box.com/oauth2/token';");

Using a data source: 

AutoRESTDataSource mds = new AutoRESTDataSource();
mds.setDescription("My Autonomous REST Data Source");
mds.setAuthenticationMethod("OAuth2-AuthorizationCode");
mds.setClientID("abcdefghij1k2lmn3o4p5qr67s");
mds.setConfig("C:/path/to/box.rest");
mds.setOAuthCode("xyz123abc");
mds.setTokenURI("https://api.box.com/oauth2/token");