The OpenID Connect Provider from BankID (hereafter referred to as the OIDC Provider) consists of a industry-standard REST API in front of various Identity Providers (IDP) and Supplementary Services as illustrated below. The REST API is based on OpenID Connect 1.0 being an identity layer on top of the OAuth 2.0 authorization protocol framework.

A major benefit of the OIDC Provider is to allow merchants start using the BankID Services with minimum integration effort compared to the legacy integration option (ie. install BankID Server, add a BankID merchant certificate and integrate towards the proprietary API of BankID server). For the xID Service there is no other integration option available to merchants than via the OIDC Provider. 

The  Additional Information service is available via standardized scopes, claims and token formats over the Userinfo endpoint according to the OpenID Connect Specification. The PSD2 service consists of a range of specific OAuth2 scopes, claims and token formats tailored for various use-cases under PSD2.

The generalized term OIDC Client is used for any application that integrates with the OIDC Provider. This term corresponds to the following terms in related vocabularies:

• OAUth2 clients in OAuth vocabulary
• Relying Party in OIDC vocabulary
• Merchant in BankID vocabulary
• Third Party Provider in PSD2 vocabulary.

OIDC Clients may integrate directly with the OIDC Provider as shown in the below figure or in an indirect configuration via an intermediate party as described in a separate section. 

The OIDC Provider comes with default GUI experiences for each of the supported IDP options. The default experience may differ as described separately for each of the IDP options.  An OIDC Client may override the default GUI experience and provide its own customized dialogues hosted at any URL.

Generic aspects of the OIDC Provider are described in subsequent sections on this page. Specific aspects for each of the supported IDP options and Supplementary Service options are described on separate pages.

Availability and access

The OIDC Provider is currently available in three different pilot configurations supporting various feature options. All features will be consolidated into one single configuration after the pilot phase. Each of the configurations are in turn available in different environments (preview, pre-prod, prototype).

For further details on access URLs for each of the configurations, see separate pages for BankID, xID and PSD2.  

Protocol flow

The below figure shows the protocol flow that is currently supported by the OIDC Provider, corresponding to an hybrid flow in OAuth2 vocabulary. Support for other OAuth2 flows (code grant flow and implicit grant flow) will be added in future versions of the OIDC Provider.  

The following parties are involved in this particuar flow:

• End user - The user owns resources that the OIDC Client requests access to. Some resources may require an explicit consent from the user in the course of the protocol flow.
• User-Agent  - A browser, or a browser window in an application, allowing the user to navigate the OIDC Client and interact with the other parties involved via re-direction of requests through the User-Agent.
• OIDC Client - The application that needs to assure the identity of the end user and gain access to various resources. 
• OIDC Provider - The platform from BankID that supports the OpenID Connect standard on top of the OAuth2 protocol framework. 
• OIDC GUI - A service that is responsible for all GUI handling required by the OIDC Provider. The OIDC Provider comes with a default GUI service that is used unless it is overridden by the OIDC Client.
• Selected IDP Service - A designated IDP among all IDP options supported by the OIDC Provider that is selected by the OIDC Client and/or the end user in this particular case.
  
• Additional Info Supplementary Service -  A service, available over the standardized OIDC Userinfo endpoint, that returns additional information on the end user beyond what is returned directly in the ID Token by the OIDC Provider.

Gliffy Macro Error

Cannot find a diagram with these parameters:

• Name: oidc hybrid flow

---

Diagrams with the same name were found on the following pages:

Hover over the link to preview, click to set.

OpenID Connect Provider from BankID

Message flow details

Message flow details

OpenID Connect Provider from BankID

Message flow details

OpenID Connect Provider from BankID

OpenID Connect Provider from BankID

Message flow details

OpenID Connect Provider from BankID

Message flow details

The shown protocol flow consists of the following steps, some of which are optional.

1. x
2. x
3. x
4. x
5. x
6. x
7. x
8. x
9. x
10. x
11. x
12. x
13. x
14. x
15. x
16. x
17. x
18. x
19. x
20. x
21. x
22. x
23. x

The following protocol steps are involved:

• Pre condition: Resource Owner starts Client with a request from the User-Agent. The Resource Owner is not previously authenticated.
• A: Client redirects the User-Agent to Authorization Server with an authorization request. Parameters to the request identifies Client, lists resources needed (scopes), supplies an URL to where control is to be returned - to name a few.
• B: Authorization server triggers display of end-user dialogues to complete authentication. The dialogues shown will depend on any login_hint provided by the Client. BankID OIDC currently supports both BankID på mobil or Banklagret BankID. (Note: The Client is kept out of this dialogue - this is intentional so the Client cannot replay an authentication at a later stage.)
• C: Authorization server returns to Client with authorization_code and id_token - if Client is authorized for openid extention. Id_token contains claims with identity info so the Client may know the identity of its user. The authorization_code is used to obtain access to resources
• D: The Client requests for an access_token  used for sending requests to Resource Server. Client needs to supply with Client_id, client_secret (password), authorization_code, redirectURL (for control purposes) and some more. (Note: This request does not go through the User-Agent. This is a security feature. The client_secret and the returned access_token is not exposed to the User-Agent.)
• E: Authrorization Server responds with an access_token and a list of resources (scopes) that are available with the user's consent.
• F: The Client can request resources with the access_token as a proof of authorization (bearer token).
• G: Resource Server validates the access_token by caling the introspect endpoint of the Authorization Server and gets metadata from the access_token in return. In case of BankID OIDC this is user information and a list of audience (allowed resources).

Steps F and G can be repeated on several Resource Servers until the access_token expires.

Implementing an OIDC Client

Please see source code on GitHub for examples on how to implement an OIDC Client for the OIDC Provider.

An OIDC Client will follow these steps to authenticate an end user. Note that these steps corresponds to an OAuth2 hybrid flow that is currently supported by the platform:

1. Send an authorization request to OIDC Provider and wait for response on the redirectURL address. A scope parameter supplied with the request should contain "openid" and response type should contain "id_token", The id_token is as JSON structure containing user info from the authentication. The request may optionally include a login_hint to request as specific type of IDP, (e.g. netcentric or mobile for BankID) and/or to pre-feed any user-id that the end used would otherwise need to type in (eg. National Identity Numer and/or Mobile Number in the case of BankID).
2. The OIDC Provider returns with a response back to the Client after the autentication of the end user. The response body should contain the id_token. 
3. The OIDC Client now has the identity and other selected properties of the current user. The property/claim named "sub" contains a unique GUID of the current user (also referred to as BankID PID or SERIAL)
4. An access_token is required to enable the OIDC Client to get Additional Information by requesting the UserInfo endpoint. This currently only concerns the Norwegian National Identity Number (nnin) in case of BankID. To get access to nnin  the authorization request scope must contain "nnin" and return type should be "code id_token". The response body, from point 2, will additionally contain an autorization_code. This authorization_code is used to call the Token endpoint (client_id and client_secret is used for basic authentication of the request) to obtain an access_token.
5. Use the access_token in the authorization header as a "Bearer" token to request the UserInfo endpoint. The response will contain a JSON structure which is much like the id_token, but with addition of "nnin" (client must be approved to use scope "nnin").

Note: Id_tokens should be validated for security reasons. There are several frameworks for working with OIDC. Some fameworks have automatic support for validating the id_token before getting access to it, and some publish example code for doing so. The published examples may be used as a template.

The REST API

The REST API for the OIDC Provider consists of various end-points according to the OpenID Connect and OAuth2 Standards.  

Refresh token

 (Note: the OIDC Service does currently not support refresh_tokens)

Discovery/meta data.

https://preprod.bankidapis.no/oidc/oauth/.well-known/openid-configuration

Anonymous requests are allowed.

This end-point returns a JSON-formatted response containing key properties of the OIDC Provider.

Among other things this end-point is used to prepare for token validation.

Below is an example response from /openid-configuration for the OIDC Provider in its BankID configuration in pre-production:

{
"issuer":"https://preprod.bankidapis.no",
"authorization_endpoint":"https://preprod.bankidapis.no/oidc/oauth/authorize",
"token_endpoint":"https://preprod.bankidapis.no/oidc/oauth/token",
"userinfo_endpoint":"https://preprod.bankidapis.no/oidc/oauth/userinfo",
"jwks_uri":"https://preprod.bankidapis.no/oidc/oauth/userinfo/jwk",
"scopes_supported":[
"standard_bankid", "address", "phone",
"nnin", "openid", "profile",
"email"
],
"response_types_supported":[
"code", "token", "id_token",
"id_token token", "code token", "code id_token",
"code id_token token"
],
"response_modes_supported":[
"query", "fragment", "form_post"
],
"grant_types_supported":[
"authorization_code"
],
"subject_types_supported":[
"public"
],
"id_token_signing_alg_values_supported":[
"RS256"
],
"userinfo_signing_alg_values_supported":[
"RS256", "none"
],
"token_endpoint_auth_methods_supported":[
"client_secret_post", "client_secret_basic"
],
"claim_types_supported":[
"normal"],
"claims_supported":[
"preferred_username", "name", "sub",
"iat", "iss", "auth_time",
"exp", "birthdate", "nonce",
"amr", "azp", "bid_code",
"aud", "at_hash", "c_hash",
"nnin", "address", "phone"
],
"claims_parameter_supported":false,
"ui_locales_supported":[
"no",
"en"
],
"login_hint_supported":"[BIM|BID][:\\d{11}][:\\d{8}][:\\d{6}] for respectively client_type, nnin, phoneNo, birthday",
"serverVersion":"bankid-oauth-api 1.2.0"
}

Getting keys to sign tokens

https://preprod.bankidapis.no/oidc/oauth/userinfo/jwk

Anonymous requests are allowed.

This end-point returns the public part of keys used for signing tokens. The keys are later used for token validations. 

Example response from /jwk:

{
   "keys":[
   {
      "kty":"RSA",
      "n":"khw6L8E9GwwTu5AUclp (abbreviated ...) OM0MdzrKLLrmgiYVi",
      "e":"AQAB",
      "kid":"bankid-oauth",
      "use":"sig"
   }
 ]
}

Authentication and authorization

https://preprod.bankidapis.no/oidc/oauth/authorize

This is a browser redirect end-point that is thoroughly described in the OIDC/OAUTH2 standards. The following query parameters pertaining to the OIDC Provider can be used:

Note: When response_type contains both id_token and code, the authorization_code is duplicated into bid_code claim in the id_token to avoid conflict with authorization_code issued by AzureAD B2C. AAD must copy the claims from BankID OIDC id_token to the one issued by AAD. The client must get an access_token from the token end-point of the BankID OIDC Service in order to use resources managed by this service. This includes the UserInfo end-point.

Below is an example id_token as returned from the OIDC Provider in its current BankID Configuration in pre-production:

{
"kid":"bankid-oauth",
"typ":"JWT",
"alg":"RS256"
}.{
"preferred_username":"Testesen, Test",
"name":"Testesen, Test",
"given_name":"Test",
"family_name":"Testesen",
"sub":"9578-6000-4-127698",
"iat":1485863742,
"iss":"https://preprod.bankidapis.no",
"auth_time":1485863742,
"exp":1485867342,
"birthdate":"1980-03-09",
"nonce":"63621460527719310(abriviated for display)c0NDk1NDIz",
"amr":["BankID"],
"azp":"DotNetClient",
"aud":"DotNetClient",
"c_hash":"SVJo7O-d4cY8N4VgiVwETQ"
}

Token

https://preprod.bankidapis.no/oidc/oauth/token

Requires basic authentication with client_id and client_secret in the Autorization header,

This end-point is used for exchanging an authorization_code with an access_token. The access_token is used for accessing resources like userinfo and potential other resource servers. The access_code exchanged was created by the authorization endpoint with a response_type containing "code"

The request should be a POST with parameters sent as "application/x-www-form-urlencoded" data.

Input:

• code=<value from authorization>
• grant_type=authorization_code
• redirect_uri=<redirect_uri used in authorization request>

Return is a JSON structure with name/value pairs.

Retrieve UserInfo

https://preprod.bankidapis.no/oidc/oauth/userinfo

BankID OIDC has implemented an UserInfo enpoint. It is implemented as a resource server and expects an access_token as a Bearer token. There are no parameters. This service is the only way to get the nnin (fødselsnummer) of the authenticated user.

Example response from /userInfo:

{
"sub": "9578-6000-4-127698",
"iss": "https://preprod.bankidapis.no",
"iat": 1485866449,
"exp": 1485870048,
"preferred_username": "Testesen, Test",
"name": "Testesen, Test",
"given_name": "Test",
"family_name": "Testesen",
"birthdate": "1980-03-09",
"nnin": "09038000010"
}

Validate access_token - introspect

https://preprod.bankidapis.no/oidc/oauth/introspect

In return the resource server get claims from the access_token including its expiration time. The return is in JSON form with a list of name/value pairs.

Characteristics of BankID OIDC access_tokens

Resources managed/authorized by the BankID OIDC Service get a “public” access_token (“one access_token to rule them all”). When an OIDC Client uses scope (or default scope) to define what resources it needs authorization for, the issued access_token can be used for all those resources. The resources must call the introspect endpoint in order to verify that it is the correct audience/resource for this access_token as well as getting returned the access_token contents/claims. Resources are expected to cache/cookie this information so there’s no need to call introspect for every incoming request with the same access_token.

The introspect endpoint demands basic authentication with the resource’s client_id and client_secret so that it knows what resource it is dealing with. 

Another policy is to have “private” access_tokens. That means each resource has their own access_token issued and encrypted with their client_secret/resource_secret. This would remove the need to call introspect in order to validate and get claims, but it will be difficult for the client to keep track of all the access_tokens issued to individual resource services. AAD is doing this and using the refresh_token to ask for more scope (new resources). This would work as long as the refresh_token is issued for the same resource owner (end-user).

"Private access_tokens" are currently not supported. Refresh_tokens are also not implemented. The rationale is that the supported “public” implementation is considered to more efficient (provided the caching we mentioned).

Database/persistence

The current implementation of BankID OIDC has no database to persist tokens. All tokens and session data resides in memory. Persistence is centralized and we aim to utilize database later. HttpSession or cookies are not in use.

Customizing the GUI experience

The default GUI experience of the BankID OIDC Service can be overridded and replaced by a customized implementation as described in the following. 

Please see source code on GitHub for an example on how to implement such a GUI customization. (TODO: Publish such an example)

GUI customization demands that OIDC Client is configured with a specific "presentationURL" paramter with the OIDC Service overriding the URL of the landing page for the default GUI.

Any GUI implementation (called "BidViewer" in the below diagramme) will interoperate with the BankID OIDC Service (the "BINAS Realm") as following: 

The authentication alternatives are

• BIM: BankID på Mobil and 
• BID: Netcentric BankID. 

The initial request to BidView will contain two parameters:

• sid - a session ID which must be used in all communication with BankID OIDC.
• oidcAuthenticationUrl - base address of the BankID OIDC API. The GUI implementation must use REST-services exposed by this API.

Here is a list of REST endpoints to be used by BidView (GUI) whith explanations:

queryGUI

To be able to display a concent screen like the one below, some extra information needs to be stored connected to each scope used by the OIDC Client. BankID OIDC will only give a list of scope names/IDs that requires user's consent. A description for each of those needs to be provided in the appropriate locale.

Indirect use of the OIDC Provider via an intermediate party

BankID OIDC has been tested with success as an identity provider for Azure AD B2C in a configuration setup as shown below. 

 identity provider for Microsoft Azure AD B2C.

May also use bid_client_id in the request parameter (mandatory when passing through an intermediate OIDC Provider that have its own client_id).

Test of thus setup has been made available via a private preview of Azure AD B2C from Microsoft. When Azure AD B2C becomes generally available (tentative Q217) this documentation will be updated on how to use BankID OIDC in such a context. 

Applications connecting via Azure AD B2C can be offered the same set of services from BankID OIDC as for those applications that integrate directly with BankIDOIDC.

Some notes on usage:

• Authorization request must contain bid_client_id: Meaning the client_id given by BankID OIDC. The client_id value will be treated as an intermediate client (ex: MS Azure). Legal scopes are openid pluss all scopes registered for the BankID OIDC client. The resulting id_token returned to Client holds a value bid_code which is an authorization_code for accessing UserInfo on BankID OIDC (provided that scope and return_type is correct) . Resulting audience in id_token will be set to bid_client_id and client_id of the AzureAD requestor in combination.
• Some parameters may need to be prefixed with "bid_" in order to pass through AAD B2C. AAD B2C is also a OIDC Service and parameters are part of the standard.