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
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
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
scope is no longer supported in the v0 endpoints. See the Claims section for instructions on requesting
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
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.
claims must now be requested by a client via the OpenID Connect
parameter. See the Authentication Framework docs for information on how to request specific
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
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
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.