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.
The new v0 endpoints have breaking changes from their original unversioned counterparts.
Deprecation of Unversioned Endpoints
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
This includes the OpenID Connect Discovery endpoint:
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.
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
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.
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)
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.
Take a look at specific documentation in the API Reference.