Auth Code Flow

Quickstarts

Quickstarts are designed to help get you up and running fast.

After completing a Quickstart, continue your learning journey by diving into the API Reference, UX Flows, and other guidance within this Jack Henry Identity site.

• Prefer the command line?
  • Try the Authentication - Authorization Code (Command Line) quickstart.
• Prefer Node.js?
  • Try the Authentication - Authorization Code (Node.js Example) quickstart.

Note, the Authorization Code Flow Quickstarts are contained within the Banno Admin API portion of the site. That’s because the authentication framework was initially developed for use with our Banno Admin and Consumer API’s. We’ve extended and enhanced the functionality to support all of Jack Henry, and are working to get documentation updated across the interconnected parts of jackhenry.dev.

Decisions / Need to Knows About Your Approach

1. Backend For Frontend (BFF) architecture is strongly recommended for everyone (and is required for all JH products to ensure no tokens can be extracted from the browser).
2. Will your product use a client secret or a signed JWT (private key JWT) for client authentication?
3. If your users will need to be presented with a list of institutions they’re allowed access to, where will that information come from?
4. What scopes do you need, and how will they be enforced?

Client secret vs Signed JWT

While using a client secret is common, you should consider the alternative of passing a signed JWT for improved security.

With that approach a signed client assertion JWT is passed to the OpenID provider, which only has access to the public key. It’s critical that the private key be handled securely and kept private.

This reduces the risk of a client secret being intercepted, and an attacker impersonating the client.

If you take this approach, you’ll also need to decide whether to provide your public key as a JWKS URI or in PEM format.

If you intend to rotate public keys, then a JWKS URI is required so you can rotate without downtime, and without Jack Henry Identity operational teams needing to be involved. Jack Henry will only support rotation of keys for cause, rather than on a fixed interval.

List of Institutions

While Jack Henry Identity is an authentication system, versus permissions or authorizations, there’s one important intersection between the two, related to which institution(s) a user is allowed to access.

During Jack Henry Identity authentication, users often begin the flow in a state where they’ve not yet selected a specific institution. After successful authentication if the institution hasn’t already been selected, users are typically presented with some mechanism to select which institution they wish to access within a product. For a good user experience, the choices they see should make sense based on the permissions or entitlements the user has for the product.

Example - Banno

Banno customers who need to access the back office application navigate to https://banno.com/a/login. The OAuth redirect to the Jack Henry Identity login page happens and, after successful authentication, the user would be issued an access token for the institutionId that represents Jack Henry Identity in our system.

With this token, a user would be authorized to access their Jack Henry Identity profile and security settings.

Next, users who have access to more than one institution are presented with a list so they can select the one they’re trying to access.

In this example, “users who have access to more than one institution” could be defined as, users who’ve been invited to a Banno Group for more than one institution through the Users & Groups application in Banno Admin, and who belong to one or more groups for multiple institutions.

What does that mean for my product?

It depends on what your product’s authorizations story is.

1. Where do your permissions live?
2. How do you control which users have access to which parts or features of your product?

JH Authorizations Management System (AMS)

If the answer is that your product uses AMS’s group-based access control, then permissions for your product are assigned through Platform Groups within the Users & Group application in Banno Admin.

There’s not yet a publicly available API to return all the institutions for a user based on membership in AMS / Platform Group membership.

Until then, it’s an option for products to utilize an API that returns all the institutions for a user based on membership in Banno Groups. Since the Users & Group application currently requires every user to belong to at least one Banno Group (whereas AMS / Platform membership is optional), this API could work for your product.

Alternatively, a product using AMS could choose to use its own logic to present a list of institutions to their users. Once a selection is made, the OAuth flow would be triggered to obtain an access token for the selected institutionId.

Factors to weigh:

1. Using the pre-existing API may save development time compared to creating your own solution.
2. Using the pre-existing API means that every user who needs access to an institution for your product will need to be invited through the Users & Group app in Banno Admin for each institution. That includes Jack Henry employees (e.g. support staff).

Something besides AMS

If your product does not use AMS group-based access control for permissions, then you may wish to use your own logic for deciding which institutions to present to each user, based on the instances they should have access to within your product.

It’s an option to rely on the API that returns all the institutions for a user based on membership in Banno Groups. This requires each user to be invited to each institution they need access to, including operational staff who need access for supporting a product integrated with Jack Henry Identity. That should be considered when deciding whether to utilize the provided API, versus handle it within the product. Enhanced options will exist in the future.

Scopes

If you’re new to working with scopes, start by reviewing the general concept.

Scopes define the categories of data that can be accessed and the operations that can be performed. In general, scopes are less granular than permissions and a single scope may cover multiple API’s.

Example

Let’s pretend the following API’s need to be supported:

• GET /{InstitutionUniversalId}/enterprise/{EnterpriseUserId}/accounts/{Id}
• GET /{InstitutionUniversalId}/enterprise/{EnterpriseUserId}/accounts/{Id}/account-summary
• GET /{InstitutionUniversalId}/enterprise/{EnterpriseUserId}/accounts/{Id}/available-balance
• POST {InstitutionUniversalId}/enterprise/{EnterpriseUserId}/accounts/inquiry
• PUT {InstitutionUniversalId}/enterprise/{EnterpriseUserId}/accounts/{Id}
• PATCH {InstitutionUniversalId}/enterprise/{EnterpriseUserId}/accounts/{Id}/dates
• PATCH {InstitutionUniversalId}/enterprise/{EnterpriseUserId}/accounts/{Id}

It could make sense to support the following scopes:

• https://jackhenry.com/account-services/accounts.read, applied to the following endpoints:
  • GET /{InstitutionUniversalId}/enterprise/{EnterpriseUserId}/accounts/{Id}
  • GET /{InstitutionUniversalId}/enterprise/{EnterpriseUserId}/accounts/{Id}/account-summary
  • GET /{InstitutionUniversalId}/enterprise/{EnterpriseUserId}/accounts/{Id}/available-balance
  • POST {InstitutionUniversalId}/enterprise/{EnterpriseUserId}/accounts/inquiry
• https://jackhenry.com/account-services/accounts.write, applied to the following endpoints:
  • PUT {InstitutionUniversalId}/enterprise/{EnterpriseUserId}/accounts/{Id}
  • PATCH {InstitutionUniversalId}/enterprise/{EnterpriseUserId}/accounts/{Id}/dates
  • PATCH {InstitutionUniversalId}/enterprise/{EnterpriseUserId}/accounts/{Id}

Remember, the scopes apply to the OAuth client (i.e. external application), not the {EnterpriseUserId}.

The {EnterpriseUserId} in the example API request paths likely also needs to have some relevant permissions. In many (but not necessarily all) cases, those permissions will be more granular than the scopes.

Additional resources to support the implementation for Jack Henry product teams are available from the Developer Relations group.