Page tree
Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 179 Next »

The OpenID Connect Provider from BankID is a platform supporting multiple Identity Provider (IDP) options, among them BankID and xID.

The platform provides ID Tokens for authenticated users and Access Tokens to authorize access to various Supplementary Services on behalf on the user.

The OIDC Provider is currently in pilot for evaluation purposes and shall not be used for commercial applications.

The platform may be augmented with more IDP options and Supplementary Service options in the future.

The OpenID Connect Provider from BankID (hereafter referred to as the OIDC Provider) is illustrated below. It consists of a industry-standard REST API in front of various Identity Providers (IDP) and Supplementary Services. The REST API is based on the OpenID Connect authentication standard on top of the OAuth 2.0 authorization 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  the OIDC Provider is the only integration option available to merchants. 

The  Additional Information service is available over the Userinfo endpoint according to the OpenID Connect specification and uses standardized scopes, claims and token formats . The PSD2 service does in contrasts consist of a range of specific OAuth2 scopes, claims and token formats tailored for various use-cases under PSD2.

The term OIDC Client is used for any application that integrates with the OIDC Provider, corresponding 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.

See below for how to register an OIDC Client to gain access to the OIDC Provider from BankID. See also source code on GitHub for various examples on how to implement OIDC Clients for the OIDC Provider.

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

The OIDC Provider comes with a default component responsible for all GUI handling.  An OIDC Client may override the default GUI and provide its own customized GUI handling hosted at any URL.


Availability and access

The OIDC Provider is currently available in three different pilot configurations supporting various feature combinations. 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).

 IDP optionsSupplementary ServicesEnvironment
Pilot configurationBankIDxIDAdditional InformationPSD2PreviewPre-prodPrototype
BankID pilotX X XXX
xID pilotXXX XXX

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

Please contact to request access to any of the pilot configurations in any of the environments.

The following information must be supplied by the owner of the OIDC Client that requests access. Sucessfull enrollment will result in the return of a client_id and a client_secret to the application owner.

  • Description on what the OIDC Client is going to be used for
  • Contact information for both technical and commercial requests.
  • Optionally a BankID Merchant certificate to be used for the Client, thus replacing the default certificate of the OIDC Service itself.
  • Requested user properties or resources (scopes). 
  • One of more URLs where control will redirected back to the OIDC client (redirect URLs must be pre-registered for safety reasons).
  • A display name for the OIDC Client that will be shown in the header of the (default) OIDC dialogues.
  • Optionally an URL for custom GUI handling overriding the default GUI component of the OIDC Provider.

Protocol flow

The below figure shows an example 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 applies for this particular example:

  • The OIDC Client uses the default GUI of the OIDC Provider
  • The OIDC Client leaves selection of IDP Option to the End User in a selector dialogue provided by the OIDC Provider
  • The OIDC Client requests access to reseources that is available via the Additional Info Supplementary Service.

The following color coding is used:

  • Red color corresponds to application-specific flows for the OIDC Client
  • Blue color corresponds to standardized flows according to the OpenID Connect and OAuth2 specifications.
  • Black color corresponds to specific flows for the OIDC Provider from BankID
  • Yellow color corresponds to specific flows for the designated IDP.
  • Green color corresponds to specific flows for any Supplementary Service (Additional Info in this particular example).

Note that an OIDC Client only concerns standardized flows (blue color) with the OIDC Provider. The exception is if the OIDC Client wants to override default GUI handling. Any component responsible for customized GUI handling must integrate with a specific REST API (black color) of the OIDC Provider. Any such component must in addition take care of proper integration with each of the supported IDP options (yellow color).

Gliffy Macro Error

Cannot find a diagram with these parameters:

  • Name: oidc hybrid flow

The following actors are involved in the protocol flow:

  • End user - The user owns resources that the OIDC Client requests access to. Some resources may require an explicit consent from the user before the OIDC Client is granted access.
  • 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 request access to various resources. 
  • OIDC Provider - The platform from BankID that provides an OpenID Connect / OAuth2 interface in front of a range of IDPs  and Supplementary Services.
  • OIDC GUI - A service that is responsible for all GUI handling associated with OIDC Provider. The OIDC Provider comes with a default GUI service that is used unless it is overridden by the OIDC Client.
  • IDP Service - A designated IDP selected by the End User among all IDP options supported by the OIDC Provider (in other cases the OIDC Client may select the designated IDP option).
  • Additional Info 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 itself.

The protocol flow consists of the following steps, some of which are optional. (TODO: add hyperlinks to the below list)

  1. The End User navigates the OIDC Client via the User-Agent and selects a login action.
  2. The OIDC Client redirects the User-Agent to the OIDC Provider with an authorization request. Parameters to the request includes the ID of the OIDC Client, list of requested resources (scopes), a redirectURL to where control is to be returned - to name a few. The OIDC Client will regain control in step 16 at the designated redirectURL.
  3. The OIDC Provider opens a session and redirects the User-Agent with an authentication request to the designated URL for GUI handling, which in this case corresponse to the default GUI component. Parameters to the request identifies the session in progress.
  4. The GUI component requests parameters from the OIDC Provider for the session in progress to determine if the OIDC Client has pre-selected a specific IDP or if a selector dialog should be shown to the end user
  5. A IDP selector dialog is (optionally) shown to the end user.
  6. The GUI component sends an init request to the OIDC Provider for the designated IDP Service
  7. The OIDC Provider sends a corresponding init request to the designated IDP Service which opens a session and responds with the necessary parameters to lauch the GUI for the designated IDP
  8. The OIDC Provider returns the necessary parameters to the GUI component
  9. The GUI component delivers the GUI for the selected IDP to the User-Agent
  10. The End User interacts with the IDP GUI, which in turn communicates with the IDP Service. Note that the OIDC Client is kept out of this dialogue to prevent any replay attack from any malicious OIDC Client.
  11. After completing the session with the IDP Service, the User-Agent is redirected back to the OIDC Provider with an authentication response. The End User is now authenticated.
  12. The OIDC Provider redirects the User-Agent to the GUI component for consent handling
  13. The GUI component requests from the OIDC Provider which scopes have been requested by the OIDC Client for the session in progress,
  14. After analyzing how the requested scopes may demand explicit consent from the user, the required GUI dialog is returned to the User-Agent for the End User to give his consent.
  15. The User-Agent is redirected back to the OIDC Provider at termination of the consent dialogue. The ID Token for the authenticated user is now being composed according to the reqested scopes.
  16. The ID Token is retuned to the OIDC Client via a redirect of the User-Agent, corresponding to a hybrid OAuth2 flow. An intermediate authorization code is also returned in this step that is used in the next step to request any access token.
  17. The OIDC Client exchanges the authorization code from the previous step for an access token with the OIDC Provider, which in this case is a token to gain access to the Additional Info Service over the Userinfo endpoint. Note that the request for an access token does not go through the User-Agent for security reasons. 
  18. The OIDC Client sends the Access Token in a request to the OIDC Provider to get access to Additional Info via the Userinfo endpoint.  The Access Token is a bearer token that provides proof of authorization by the End User.
  19. The OIDC Provider validates the provided access token via the Introspect endpoint.
  20. After sucessfull validation of the Access Token, the OIDC Provider retrievs Additional Anformation from the back-end part of the service.
  21. The Additional Information in question is returned to the OIDC Client in a Userinfo response.
  22. The OIDC Clients returns to the User-Agent a page showing the reponse of the login request along with any Additional Information that was retrieved.

OpenID Connect REST API


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

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:


This is a polling function to be notified when a BankID på Mobil authentication has ended (hopefully with success).

Http status code 200 is used to indicate that BankID OIDC has got the terminating "verifyAuth" or "handleError" notifications.

Http status code 204 is returned while the authentication is still in process.


When the BidView (GUI) is called, with sid (session ID) as parameter, it can send a queryGUI request to get session based info in return:

  • applicationName - application name of the client to be used in dialogues.
  • merchantName - merchant name for this BankID session to be used in dialogues.
  • ui_locales - list of language options to use for dialogues
  • bankidLocale - the language option to use for BankID dialogues ('nb' or 'en')
  • cancelUrl - a redirect address if user hits the cancel button
  • clientType - BIM or BID (BankID mobile or netcentric)
  • phoneNo - If specified to be used for BIM authentication
  • birthday - If specified to be used for BIM authentication
  • nnin - If specified to be used for BID authentication.

Start the merchant back end session for Banklagret BankID.

Input parameters:

  • sid - session ID
  • nnin - (optional) 11 digit Norwegian national ID/fødselsnummer
  • bankidLocale (optional) BankID language setting ('nb' or 'en').

Returned parameters:

  • returnUrl - where to redirect when authentication is finished.
  • bidHelperUri - address of the BankID startscript (with Init() method).
  • cid - the backend session ID
  • errorCode and errorMsg if call failed.

Initiate a BankID på Mobile authentication


  • sid - session ID
  • phoneNo - Mobile phone number (8 digits)
  • birthday - DDMMYY
  • bankidLocale - (optional) Language setting (currently only Norwegian is offered).


  • returnUrl - address where to return after authentication is finished
  • mobilePollerUrl - where to require if BIM authentication is finished (see "bimfinished" above).
  • merchantReference - the words to display for the user to verify on phone message.
  • errorCode and errorMsg - (optional) if call failed.

When the GUI shall build the consent screen this REST-call is needed to retrieve information.

Input: sid -session ID


  • replyHref - an incomplete address to use the consent. It is made complete by appending "allow" or "deny" depending upon user's choice.
  • application - application name to be displayed in dialog.
  • merchantName - name of the BankID merchant
  • personName - name of the user
  • scopes - a space separated list of scope names we need concent on.
  • bankidLocale - language of the dialog.
  • errCode and errMsg - (optional) if error occurs.

This is used for handling the user canceling out of BankID authentication or concent screen notifying BankID OIDC backend.

Input is sid - session ID.

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.


  • No labels