Authenticate Users in your App using OpenID Connect

Applications will need to authenticate in order to be able to be authorized or authenticated to use features of the API. To learn more about the basics of authentication and authorization, see Authorization and Authentication.

Note: You will first need to set up a Dev Portal account.

Which Method of Authentication do I Need?

This tutorial will guide you through setting up OpenID Connect authentication, which is meant for services that have users, such as web and mobile applications.

Currently, applications that do not have users cannot authenticate at this time. Application-based authentication is currently in development.

For a conceptual explanation of the authentication and authorization, please see Authorization and Authentication.

Apiture API Account Creation

Before any authentication code is written, your company and app will first need API Keys which are provided directly by Apiture. 

Where to Authenticate

To initiate authentication, the client must know where to authenticate the user and where to obtain the access token. OpenID Connect provides a discovery mechanism for this. The client begins by fetching the OpenID Connect configuration JSON data from the target environment. Target environment URIs are available in the logged into your Dev Portal Account.

Note: The below URIs will not be accurate for your environment. Perform the below requests demonstrated in this guide on your environment for accurate data.

For example, if your target environment was DevBank, the environment’s URI would be api.devbank.apiture.com. To gather the OpenID Connect configuration URL, GET api.devbank.apiture.com/auth/. 

Use an HTTP GET on the URI in the href property to fetch the configuration data, and save the authorization_endpoint, token_endpoint, userinfo_endpoint and other connection parameters that are used to complete the authorization flows.

OpenID Connect Authorization Code Flow

OpenID Connect performs a series of checks and redirects, sending the user to a log in form and eventually granting a token for API access. For the secure user login, the application will redirect to the Apiture authorization server. The user will log in on this authorization server.

After logging in successfully, the user is redirected back to the requesting application using the callback URI associated with the client application. This URI is set up in your Dev Portal account.

The application’s Authentication type must be set to Authorization Code in the Dev Portal.

  1. The client makes an authorization request by sending a GET request to the authorization_endpoint from the OpenID Connect configuration data, passing several query parameters in the URI:

  • state={state} where {state} is a client generated random string.
  • scope=openid
  • response_type=code
  • client_id={clientId} where {clientId} is the registered client credential ID for that environment.
  • redirect_uri={url-encoded-redirect-uri} where {url-encoded-redirect-uri} is the callback URI associated with the client application. This must match the URI entered in the configuration in your Dev Portal account.

2. The authorization_endpoint validates the query parameters.

  • If the parameters are valid, the user will be directed to a form to enter their login credentials. The user may also be prompted to give consent to specific application access. Note: The client application does not need to pass the user’s credentials to authenticate.
  • If the parameters are invalid, the request will fail with a 4XX error.

3. If the client request and user authentication credentials are valid, the authorization request returns a 302 response. In the response, a Location header exists that contains the client redirect URI that is set up in your Dev Portal account, a code which will be used to generate an access token later, and the client state value that was passed in the original request.

If the user cannot be authenticated, they will be notified of a potential error. Client-side code does not need to handle this validation.

4. The client redirects to the redirect URI where the client will process the response. That client should ensure the state matches the one passed in the original request and should stop the flow if they do not match.

5. If the state matches, the client must exchange the code for an access token to complete authorization. This step should be done securely in your server-side code connected to the redirect URI. This is done by a POST request to the token_endpoint URI passing:

  • An Authorization request header with the client credentials in the form
    Basic:encoded-credentials}
    where {encoded-credentials} is a Base 64 encoding of the text client-id:client-secret for the registered client.
    • Warning: Avoid calling the token_endpoint directly from a web or mobile client, as this allows easy inspection of the HTTP request and the decoding of the client ID and secret from the Authorization header.
  • Pass the parameters as form data using Content-Type: application/x-www-form-urlencoded. The form data consists of three values:
    • grant_type:
      This must be set to authorization_code during initial authentication. grant_type is required.
    • code:
      This must be set to the authorization code returned via a callback redirect after performing the authorize request. This is required if grant_type is authorization_code.
    • redirect_uri:
      The URI-encoded callback URI for user redirection after a successful authentication request. This value must match the value used during the client application registration process and the value passed to authorize. Required if using the authorization_code flow.

6. The response is a JSON body with four properties:

Name (Type) Description
access_token (string) An opaque string which should be passed along with the token_type to subsequent API calls which require authentication.
token_type (string) The form of token returned. This is typically the string Bearer: and the key which subsequent calls should use in the Authorization header when making authenticated API requests.
expires_in (integer) The number of seconds until the access_token expires. Before it expires, use the refresh_token grant type to request a new access token.
refresh_token (string) A token to use when the access_token expires. The client should retain this securely so it can obtain a new access_token before the current access token expires.

The client combines token_type and access_token to form the Authorization header for API requests that require secure authorization, using this request header:

Authorization: token_type access_token

For example, if the token_type is Bearer and the acquired access_token is C1AC67D1EB404070B61DB7ECD5C635A7, the request should use

Authorization: Bearer C1AC67D1EB404070B61DB7ECD5C635A7

Refreshing Tokens

Tokens will expire when the expires_in countdown reaches zero. The token should be refreshed before then to keep the user logged in.

To refresh a token, send a POST request to the token_endpoint URI passing:

  • An Authorization request header with the client credentials in the form
    Basic:{encoded-credentials}
    where {encoded-credentials} is a Base 64 encoding of the text client-id:client-secret for the registered client.
    • Warning: Avoid calling the token_endpoint directly from a web or mobile client, as this allows easy inspection of the HTTP request and the decoding of the client ID and secret from the Authorization header.
  • Pass the parameters as form data using Content-Type: application/x-www-form-urlencoded. The form data consists of two values:
    • grant_type:
      This must be set to refresh_token when renewing an expired or expiring access token. grant_type is required.
    • refresh_token={refresh_token}:
      {refresh_token} must be replaced with the refresh token saved from the initial authentication.

On this page