Overview
In this image, an end user uses either a web site, mobile or desktop application and needs to access API or a web site.
Those scenarios are supported via OAuth 2 RFC 6749
- Authorization Code Grant, RFC-6749 section 1.3.1
- Implicit Grant, RFC-6749 section 1.3.2
- Client Credentials, RFC-6749 section 1.3.4
- Client Authentication with JWT RFC-7523 section 2.2
- Token ExchangeRFC-8693
We do not support Resource Owner Password Credential 1.3.3 as it requires the user to put his password on the client device.
We support Open ID Connect specification. To have ID token and session state, include the scope of "openid" in the authorization request.
Protocol Flows
User Authentication
A user needs to access an API or just to authenticate to some client application
- The application he/she operates performs a browser redirect to the authorization endpoint.
- The authentication server executes the requested authentication sequence.
- After the authentication, the authorization server asks for the user's consent to perform the requested action.
- The result (authorization code, access token, id token, and session state) is returned either via browser redirect or form post.
- If an authorization code is returned, the application needs to make a call to the token API to get the access token and, optionally, the ID token. If an ID Token is returned, it needs to be validated.
- The application can use the access token to access the API. Optionally, it can use the ID token for authentication.
Client Authentication
A client needs to access an API. There is no user in this scenario. Open ID Connect does not apply
- The client submits its credentials to the token endpoint. If successful, receives an acecss token.
- The application can use the access token to access the API.
Metadata
We use Open ID Connect Discovery to advertise the metadata. The metadata addresses are:
| Region | URL |
|---|---|
| QA | https://authenticate.qa.bnymellon.com/.well-known/openid-configuration |
| Production | https://authenticate.bnymellon.com/.well-known/openid-configuration |
Note: Only Production and QA regions are available externally.
Important Metadata:
- authorization_endpoint — The authorization endpoint URL. The client applications need to redirect to this URL for authorization requests.
- token_endpoint — URL of the Token Endpoint, where the authorization code can be replaced for the access token.
- userinfo_endpoint — URL of the UserInfo API. Can only be used for Open ID Connect access tokens to retrieve user profile.
- jwks_uri — URL to return public keys in JWKS format ( RFC 7517 ). The keys can be used to validate the ID token.
User Authorization Request and Response
When a user needs to access a protected resource. The application, which will access the resource, needs an access token (optionally ID token). It redirects the authorization request to the URL, specified in the "authorization_enpoint" of the metadata. The format of the authorization request is described in RFC 6749
- For Authorization Code grant, section 4.1
- For Implicit grant, section 4.2
- Open ID Connect uses additional parameters, described in Open ID Connect Core, section 3.1.2
Supported Request Parameters
- response_type — Either "code" or "implicit"
- scope — To use Open ID Connect, include "openid". Other scopes are not supported yet.
- client_id — The consumer key, obtained from the API store.
- redirect_uri — Where the response to be returned. MUST MATCH exactly the one, registered in the API store.
- state — Optional value, to maintain the state at the client between the request and response.
- prompt — One of "none", "login", "change_password". The last is used to force a password change.
- acr_values — Optional, requested authentication context reference. Supports:
- "urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport" — This is the default option. Uses user/password authentication.
- "urn:federation:authentication:windows" — Integrated Windows Authentication. Supported for Internal Applications only, hosted/browsed on BNYM network via a BNYM Windows Desktop.
- "urn:bnym:rsa:aa" - Adaptive Authentication.
- "urn:bnym:rsa:PasswordAndTimeSyncToken" - Password and Secur ID Token.
Client Authorization Request and Response
When an application needs to access a resource. There is no user, or user information is irrelevant. To get an acces token it needs to call the token API to submit its credentials. The format of the authorization request is described in RFC 6749, section 1.3.4
Only Client Authentication with JWT is available to external clients. The client certificate nedes to be registered with BNY.