Jack Henry Digital Toolkit
JackHenry.dev
Learn how to develop with Jack Henry's digital banking platform to innovate faster and deliver top-notch experiences.
Digital Toolkit
Integrate with Jack Henry's plugin framework, authentication framework, admin API, and consumer API.
Enterprise Solutions
Integrate with Jack Henry's SilverLake, CIF 20/20, and Core Director banking cores.
SymXchange
Integrate with Jack Henry's Symitar credit union core.
Payments
Embed check deposits, ACH transactions, bill payments, card issuing and processing, and real-time payments.
Design Guidelines
Create stunning products with this set of visual guidelines
Light Mode ✓
Always display this site using light mode.
Dark Mode ✓
Always display this site using dark mode.
Device Setting ✓
Display this site using this device's light / dark mode setting.

Migrating to the V0 OpenID Connect Endpoints

Consumer API > Guides > Migrating to the V0 OpenID Connect Endpoints

Banno has now upgraded the OAuth and OpenID Connect implementation which has resulted in new v0 auth endpoints. These new endpoints are available under /v0 paths.

Breaking Changes

Note
The new v0 endpoints have breaking changes from their original unversioned counterparts.

Deprecation of Unversioned Endpoints

DEPRECATION
The unversioned endpoints are now officially deprecated and support for using them will not be maintained beyond March 1, 2022.
All clients are encouraged to move to the v0 endpoints well before March 1, 2022.

The following details are provided to assist implementors in updating their applications.

Use Versioned Paths

All of the OpenID Connect endpoints now are under the /a/consumer/api/v0/oidc path.

This includes the OpenID Connect Discovery endpoint: /a/consumer/api/v0/oidc/.well-known/openid-configuration

Corrected Issuer

The unversioned endpoints all used the issuer https://www.banno.com/a/consumer/api/oidc. However, this issuer did not match the hostname which violates the OAuth2/OpenID specification. In the v0 endpoints, the issuer now correctly matches the hostname. Integrations which relied on the old issuer should update to the new issuer.

Scopes

In the unversioned endpoints, only a limited number of scopes were supported. With the v0 endpoints a much expanded set of scopes was added to control access to API endpoints. All clients using the v0 endpoints must request the proper scopes. Enforcement of these scopes is not yet enabled, but will be in the future. Clients not requesting the correct scopes will be denied access to the associated endpoints. Details on the supported scopes can be found in the Authentication Framework docs.

Scopes which control access to API endpoints must be specifically allowed in the configuration for the application. The back office administrator at your financial institution can do this for you in the External applications section of Banno People.

OpenID Connect defines a set of scopes that control claims in the returned Identity Token. These include the scopes “profile”, “email”, “address” and “phone”. These scopes continue to be supported in the v0 endpoints.

The unversioned endpoints supported a special “banno” scope which controlled custom claims returned in the Identity Token. This scope is no longer supported in the v0 endpoints. See the Claims section for instructions on requesting claims.

Claims

Banno supports a large number of custom claims. In the unversioned provider, these claims were not namespaced. In the v0 provider, these claims are now namespaced as https://api.banno.com/consumer/claim/claim_name. Claim properties in the Identity Token and returned from the UserInfo API endpoint will now include the full namespace. Clients must update to access the claim via the namespace. Details on the supported claims can be found in the Authentication Framework docs.

Custom claims must now be requested by a client via the OpenID Connect claims parameter. See the Authentication Framework docs for information on how to request specific claims.

Proof Key for Code Exchange (PKCE)

In the unversioned endpoints, only public clients were required to utilize PKCE for the authorization code flow. A public client is typically a native mobile application or a browser JavaScript application where the OAuth flow is handled completely client side. Since a client secret cannot be properly secured in these environments, the client authenticates using only the Client ID and the proof key for code exchange parameters.

However, the OAuth 2.1 draft specification requires the use of PKCE for all clients. Consequently, the v0 endpoints require the use of PKCE by default for all clients. While the PKCE requirement can be disabled for confidential clients, implementers are strongly encouraged to utilize PKCE.

Learn more about PKCE at https://auth0.com/docs/flows/authorization-code-flow-with-proof-key-for-code-exchange-pkce.

Removal of the Implicit Flow

The unversioned endpoints provided basic support for the Implicit flow of OAuth2. The OAuth 2.1 draft specification completely removes support for the Implicit flow. The v0 endpoints no longer support the Implicit flow. All implementations must change to utilizing the Authorization Code flow.

Changes to Refresh Tokens

In the unversioned endpoints, a Refresh Token was issued when the “offline_access” scope was requested and the “prompt=consent” parameter was also included in the initial authorization request. In addition, Refresh Tokens were restricted to a single use and a new Refresh Token was issued.

The OAuth 2.1 draft specification requires Refresh Token rotation in this manner for public clients. Refresh Tokens issued to public clients are still rotated on every use and a given token may only be used once.

With the v0 endpoints, confidential clients are also issued a Refresh Token on every use. However, old tokens are no longer invalidated and may continue to be used until their original expiration date. This allows confidential client applications to obtain and utilize multiple Refresh Tokens at any given time.

Also with the v0 endpoints, the scope https://api.banno.com/consumer/auth/offline_access may be used to request a Refresh Token without including the “prompt=consent” parameter. A user will always be required to re-consent to requests issuing Refresh Tokens, but the “prompt=consent” parameter is not required to obtain a Refresh Token with this scope.

With the unversioned endpoint flows, links in Banno Apps initiated the Oauth flow on a client’s behalf and then sent the client to the callback url with the authorization code already present in the URL. While this made implementation easier, it did not support clients using a “state” parameter nor did it support requiring a user to consent to the integration.

With the v0 endpoints, the app will send the user to the callback url of a client without a code. A client is expected to redirect the user back through the standard Authorization Code flow (using PKCE). In this scenario both the state parameter and user consent are fully supported.

Next Steps

Take a look at specific documentation in the API Reference.

Have a Question?
Have a how-to question? Seeing a weird error? Get help on StackOverflow.
Register for the Digital Toolkit Meetup where we answer technical Q&A from the audience.
Last updated Mon Dec 5 2022