OpenID Connect Profile

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

OIDC Libraries

OIDC is an open standard with wide adoption. This means it’s likely the code to integrate OneID with your service already exists. The OpenID Foundation provides lists of certified OIDC libraries for different programming languages and frameworks. For Common Platforms (e.g. Shopify) we aim to develop our own integrations.

OneID OIDC Flow

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.

OAuth tokens

OneID does not support Refresh tokens. Access tokens we issue are valid for 5 minutes.

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 ,

Name.

"name":"Janet Davidson", "given_name":"Janet", "family_name":"Davidson"

date_of_birth

birthdate

Date of birth.

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

State

The OAuth state parameter is required in order to help mitigate CSRF attacks by using a unique and non-guessable value associated with each authentication request about to be initiated. The state should be passing the regular expression ^[a-zA-Z0-9\-_]+$ and should be kept in the backend, or browser’s local storage.

Upon the user’s redirection back to the return endpoint, the state found in the URL params should be compared against the one previously stored and the journey should fail if they do not match.

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.

OIDC Configuration URLs

The following URLs return our OpenID Connect Configuration. They can be used to discover where our authorization, token and userinfo endpoints are located.

  • Sandbox : https://controller.sandbox.myoneid.co.uk/.well-known/openid-configuration

  • Production : https://controller.myoneid.co.uk/.well-known/openid-configuration

Userinfo endpoint

GET /userinfo

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

Example request :

GET /userinfo HTTP/1.1
Host: controller.myoneid.co.uk
Authorization: Bearer 123

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

Token endpoint

For public clients the code_verifier would also need to be included in the POST body. However the OneID button is currently our only supported public client and takes care of this.

POST /token

Example request :

POST /token HTTP/1.1
Host: controller.myoneid.co.uk
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA

Example response :

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

{
   "access_token":"2f1f65ea-1954-4bbc-81bf-e16582b143b3",
   "token_type":"Bearer",
   "expires_in":300,
   "id_token":"eyJhbGciOiJQUzI1NiIsImtpZCI6ImhWVktTd..."
}
Request Headers
  • Authorization – HTTP Basic Authentication using the client_id and client_secret as username and password respectively.

Status Codes
  • 200 OK – Successfully accessed user identity data