This documentation describes the basic use of the OpenID Connect 1.0 (OIDC) specification in in context of Buypass services, and will also describe any general Bypass specific customizations. Note that there may be additional customizations for individual scenarios or customers not describes here.

Please see service or customer specific documentation (note that such documentation might not be public).

The extendable specification

The OIDC specification does not define how the end-user does the actual authentication on the system; wither it's by username and password, with Multi-Factor Authenticaton (MFA), Qualified Certificate (QC) on a smartcard or some other authenticator on a mobile phone.

OIDC focuses on the protocol between the client site/application (the Relying Party (RP)) and the OIDC server (the OpenID Provider (OP)). The RP is often simply referred to as the "Client" and the OP is also often referred to as the "IdP" (Identity Provider).

In addition to having multiple alternative operating modes/flows, the OIDC protocol is highly extendable and do provide several options for customization. Several properties, from authenticators to provided claims and hence the fields of the various tokens and Userinfo endpoint data, can be customized.

OIDC Terminology

This is an excerpt from the specification : OpenID Connect 1.0 (OIDC) Terminology

Authentication

Process used to achieve sufficient confidence in the binding between the Entity and the presented Identity.

Claim

Piece of information asserted about an Entity.

Entity

Something that has a separate and distinct existence and that can be identified in a context. An End-User is one example of an Entity.

ID Token

JSON Web Token (JWT) that contains Claims about the Authentication event. It MAY contain other Claims.

OpenID Provider (OP)

OAuth 2.0 Authorization Server that is capable of Authenticating the End-User and providing Claims to a Relying Party about the Authentication event and the End-User.

Relying Party (RP)

OAuth 2.0 Client application requiring End-User Authentication and Claims from an OpenID Provider.

UserInfo Endpoint

Protected Resource that, when presented with an Access Token by the Client, returns authorized information about the End-User represented by the corresponding Authorization Grant.

The UserInfo Endpoint URL MUST use the https scheme and MAY contain port, path, and query parameter components.

Flows and Grants

While OIDC define authentication flows, OAuth2 will use grants to give authorization. In short, flows and grants are both defined request-response sequences between a client and a server with the goal of issuing token(s) to the client.

Both OIDC and OAuth define Access Token and Refresh Token, but only OIDC define an ID Token. Hence, the ID Token implies (end-user) authentication, while Access Token implies authorization (of end-user and/or clients).

Below are a short summary of the flows and grants and comments about Buypass support.

Note that all flows and/or grant are only enabled in cooperation with the customer and the use-case it is intended for.

OIDC flows

OIDC define three paths (or flows) for authentication. 

The flows determine how the ID Token and Access Token are returned to the Client. The most commonly used flows are Authorization Code Flow and Implicit Flow.

Authentication using the Authorization Code Flow

One of the most commonly used flows. This flow authenticates the Client applications and does not expose any tokens to the browser (tokens are exchanged server-to-server by using a one-time code). Note that this flow require a back-end application.

This flow is supported by Buypass.

Authentication using the Implicit Flow

Commonly used for Single-Page Applications (SPA), also called Javascript applications, without any backend. This flow does not support client authentication and will expose the tokens all the way out to the browser. These are the consequences of not having a back-end service. Hence this flow is not considered as secure as the Authorization Code Flow. 

This flow is supported by Buypass (but not recommended).

Authentication using the Hybrid Flow

This is a rarely used flow which combines aspects of the two other flows. As most use-cases are covered with the two other flows, this flow is not supported buy Buypass at the moment.

The OAuth2 grants

As OIDC specification is based on OAuth2, the OAuth2 Authorization Grants are also a part of the OIDC specification

The grants determine how the Access Token are returned to the Client. Note that OAuth2 does not define any ID Token.

Authorization Code

This OAuth2 grant is the basis for the OIDC Authorization Code Flow (see above). Buypass support this grant indirectly via the OIDC flow.

Implicit

This OAuth2 grant is the basis for the OIDC Implicit Flow (see above). Buypass support this grant indirectly via the OIDC flow.

Resource Owner Password Credentials

This is basically username and password. The OAuth2 specification actually warns about this grant:

"The credentials should only be used when there is a high degree of trust between the resource owner and the client ..., and when other authorization grant types are not available".

Hence, Buypass will only make this grant available for use in very specific cases, where no other option is available. Using this grant will also require some additional security mechanism such as dedicated VPN or similar.

Client Credentials

This grant focuses on authorizing the client, and not the end-user. Used separately, this grant is typically used for API authorization and other system authorizations.

Buypass support this grant for the selected domains and services where system authentication (independently of end-user authentication) is required, or as stated in RFC6749: "...authorization grant when the authorization scope is limited to the protected resources under the control of the client..".