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
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 /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.