OpenID Connect

OneID uses the popular OpenID Connect (OIDC) protocol to securely transfer bank-verified user attributes to Relying Party (RP) services.

OIDC Profile

We support the OIDC authorization code flow. For developers familiar with OAuth this is sometimes referred to as the 3-legged OAuth journey. This is the most widely supported flow across different programming languages and technologies.

skinparam monochrome true
skinparam shadowing false
actor User

"Relying Party"->User: Page with OneID button
|||
User-->OneID: Selects Bank
OneID-->User: Authorization URL at bank
|||
User->Bank: Redirected to bank for authorization
... User authenticates at bank and consents to share their data ...
User->OneID: Returned to OneID after authorization
OneID->User: Redirect to Relying Party
User->"Relying Party": Returned to Relying Party with authorization code
|||
"Relying Party"-->OneID: Call to token endpoint with authorization code
OneID-->"Relying Party": OAuth Access Token
"Relying Party"-->OneID: Call to userinfo endpoint with access token
OneID-->Bank: Access identity data from bank
Bank-->OneID: User identity data for Relying Party
OneID-->"Relying Party": Bank-verified identity data
|||
"Relying Party"->User: Checkout with bank-verified identity data
User->"Relying Party": Confirm details and complete checkout
"Relying Party"->User: Order confirmation

Users are redirected to their bank or banking app, where they are asked to authorize access to their identity data. After consenting users are redirected (via the OneID platform) back to the relying party with a code which can be exchanged for an OAuth token. Once the client holds a token it can access the protected resources. Currently the OneID platform only supports the Userinfo endpoint, though this may change in the future as new features are added.

Table of Supported Scopes

These scopes can be configued in the OneID Button to return the following claims from the Userinfo endpoint.

Scope

Returned Claims

Description

Example

openid

sub

Subject identifier: a consistent unique identifier for an individual.

"sub":"6f35afb8-42ee-5b82-88be-29ee7dc0f762",

profile

name , given_name , family_name , birthdate

Name and date of birth.

"name":"Janet Davidson", "given_name":"Janet", "family_name":"Davidson", "birthdate":"1985-06-01"

address

address

Address information embedded in a separate structure.

"address": {"street_address":"3614 Poe Road", "locality":"Heworth", "region":"York", "postal_code":"YO31 1EB", "country":"UK"}

email

email

Email address.

"email":"janet.davidson@example.com"

phone

phone_number

Phone number.

"phone_number":"0480863009"

Currently these scopes conform to the OpenID Core standard. Support for additional scopes and changes to the returned claims may come in the future.

OpenID Connect Client Configuration

Any relying party service (e.g. ecommerce website) with a server can use an OIDC confidential client. This is the most widely supported OIDC configuration.

We recommend most relying parties would create a confidential client to support OneID. In most cases support for confidential OIDC clients already exists for common web frameworks and programming languages.

The Relying Party client configuration consists of:

  • Client ID : a uuid which identifies this OIDC client to the OneID Platform

  • Client Secret : an opaque string used to authenticate the client to private API endpoints

  • Redirect URL : the URL users will be returned to once they have authenticated and shared data from their bank. The OneID platform maintains an allowlist of these redirect URLs so changes must be reflected in the platform before a new redirect_uri OIDC parameter can be used.

  • Relying Party origins : a list of the origin server names used by the relying party. The OneID Platform uses this to secure where the OneID Button can be used.

Public Clients

Currently the only public client we support is the OneID Button itself. If you would like to implement a public client (e.g. for a native mobile application without a server) then please contact us so we can support your implementation.

It is required that all public clients must be configured to provide Proof Key for Code Exchange (PKCE, RFC7636) parameters.

Differences between Sandbox and Production

Client configurations are not shared between Sandbox and Production. New clients must be configured in the production environment.

Userinfo

GET /userinfo

Return bank-verified identity data for the user identified by the Authorization OAuth token.

Example response :

HTTP/1.1 200 OK
Content-Type: application/json

{
    "sub":"6f35afb8-42ee-5b82-88be-29ee7dc0f762",
    "name":"Janet Davidson",
    "given_name":"Janet",
    "family_name":"Davidson",
    "email":"janet.davidson@example.com",
    "birthdate":"1985-06-01",
    "phone_number":"0480863009",
    "address": {
        "street_address":"3614 Poe Road",
        "locality":"Heworth",
        "region":"York",
        "postal_code":"YO31 1EB",
        "country":"UK"
    }
}
Request Headers
Status Codes
  • 200 OK – Successfully accessed user identity data