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

Deprecation of Unversioned Endpoints

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.

State Parameter and Consent for Links in Banno Apps

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.