Authorization Code Flow

OAuth 2.0 is an open standard used for securely granting applications limited access to user resources without exposing user credentials. The Authorization Code Flow is a widely used OAuth grant type suited for applications that include a backend component capable of securely handling and storing secrets. Although you may have mobile apps or single-page applications (SPAs) in your technology stack, Jack Henry requires that you implement a backend (Confidential Client) to communicate with our APIs to ensure secure credential storage and token management.

When combined with Proof Key for Code Exchange (PKCE), this flow provides robust security.

Key Concepts and Terminology

• Resource Owner (User): The individual who owns and grants access to their protected resources.
• Client (Application): The app requesting access to user resources, which must include a confidential backend.
  • Confidential Client: Has a secure backend that can safely store credentials.
• Authorization Server (Jack Henry Authentication Framework): Issues tokens after user authentication and consent.
• Resource Server (Jack Henry APIs): Provides protected resources upon receiving valid tokens.
• Authorization Code: A temporary code issued after successful user authentication.
• Access Token & Refresh Token: Tokens enabling the client to access resources; refresh tokens allow obtaining new access tokens.
• Redirect URI: Endpoint in the client’s backend that receives the authorization code after authentication.

When to Use the Authorization Code Flow

• Server-side web applications with a backend that can securely store credentials.
• Mobile or SPAs that interact with their own secure backend (which is the Confidential Client). The frontend never directly calls Jack Henry APIs; instead, it communicates with the backend, which then uses the Authorization Code Flow.

Step-by-Step Authorization Code Flow

1. Authorization Request

The client’s backend directs the user’s browser to the Jack Henry Authorization Server. This URL includes:

• client_id (application identifier)
• redirect_uri (pre-registered callback URL)
• response_type=code (specifies the Authorization Code flow)
• scope (permissions requested, e.g., openid for identity)
• state (random string to prevent CSRF attacks—see Authentication Security)
• code_challenge (Parameter for PKCE, see PKCE (Proof Key for Code Exchange))
• code_challenge_method=S256 (Parameter for PKCE, see PKCE (Proof Key for Code Exchange))

Example URL:

https://API_ENVIRONMENT/AUTHENTICATION_ENDPOINT
  ?client_id=CLIENT_ID
  &redirect_uri=CALLBACK_URI
  &response_type=code
  &scope=openid%20profile
  &state=XYZ

Notes:

• API_ENVIRONMENT could be something like digital.garden-fi.com
• AUTHENTICATION_ENDPOINT could be something like /a/consumer/api/v0/oidc/auth

With these two examples, you would send the request to https://digital.garden-fi.com/a/consumer/api/v0/oidc/auth

2. User Authentication & Consent

The user logs in to Jack Henry’s Authentication Framework. They see a consent screen listing the requested permissions (scopes). The user must explicitly approve or deny access.

3. Authorization Code Issued

After the user consents, they are redirected back to your backend with an authorization code. The redirect looks like this:

https://REDIRECT_URI/?code=AUTH_CODE&state=XYZ&iss=ISSUER

• REDIRECT_URI: The configured redirect URI.
• code: A single-use, temporary credential issued by the Authorization Server. Your backend exchanges this code for an access token (and other tokens) in the Token Exchange step.
• state: The same random, unique string you generated and sent in the authorization request. Receiving this exact same value provides protection against CSRF attacks. Always validate that the returned state matches the one you originally set.
• iss: Short for issuer. This identifies which Authorization Server (e.g., Jack Henry’s) issued the authorization code. In an OpenID Connect flow, iss is typically used to verify the origin of tokens and ensure they come from a trusted authority.

4. Token Exchange (Confidential Clients)

The client exchanges the authorization code for an access token by making a POST request:

POST https://API_ENVIRONMENT/TOKEN_ENDPOINT
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=AUTH_CODE
&redirect_uri=CALLBACK_URI
&client_id=CLIENT_ID
&client_secret=CLIENT_SECRET

Notes:

• API_ENVIRONMENT could be something like digital.garden-fi.com
• TOKEN_ENDPOINT could be something like /a/consumer/api/v0/oidc/token
• code_verifier (Parameter for PKCE, see PKCE (Proof Key for Code Exchange))

With these two examples, you would send the request to https://digital.garden-fi.com/a/consumer/api/v0/oidc/token

The server validates and returns the access token (and ID token, if requested):

{
  "access_token": "ACCESS_TOKEN",
  "id_token": "ID_TOKEN",
  "expires_in": 600,
  "token_type": "Bearer",
  "refresh_token": "REFRESH_TOKEN"
}

Using Access Tokens

Access tokens must be sent as Bearer tokens in API calls:

GET https://API_ENVIRONMENT/TARGET_ENDPOINT
Authorization: Bearer ACCESS_TOKEN

Access tokens typically expire quickly (around 10 minutes). If your application needs continual access, use the refresh token to obtain new access tokens securely on your backend.

Authentication Security

The State Parameter

• What is it? A random, unique string included in the authorization request to prevent CSRF attacks.
• How to use it:
  1. Generate a random, unguessable state value before redirecting the user’s browser to the Jack Henry Authorization Server.
  2. Send state in the authorization request.
  3. When the user is redirected back to your redirect_uri, compare the returned state to the original value.
  4. If the state does not match, abort the flow.

The Nonce Parameter

• What is it? A random, unique string used primarily to prevent replay attacks and ensure the response belongs to the original request.
• When to use it: Commonly used when requesting an ID token (OpenID Connect), especially in flows that might expose tokens in the front-end (e.g., implicit flows). Even if you’re strictly using the Authorization Code Flow, including a nonce can add extra protection for ID token verification.
  1. Generate a random, unguessable nonce.
  2. Include nonce in the authorization request.
  3. The ID token returned by the authorization server should contain the same nonce value.
  4. If it does not match, abort the flow.

Best Practices and Considerations

• Securely store credentials (for confidential clients).
• Always validate the state parameter to mitigate CSRF.
• Clearly handle errors and provide informative responses.

Troubleshooting and Common Issues