Document toolboxDocument toolbox

Authorize

The Authorize Endpoint is part of the OpenID Connect standard that starts a BankID authentication or signing of an end-user via one of the IDP options.

The Authorize Endpoint triggers a series of re-directs, eventually returning to the requesting merchant (OIDC Client) at a redirect_uri specified by the client. For security reasons, only pre-registered redirect URIs are allowed. See provisioning.

Note that BankID OIDC only supports the Authorization Code Flow with PKCE. We recommend checking out the getting started guide for how to initialise an authentication request and handle the response.

For native mobile apps, we (and RFC-8252) recommend the use of either opening the authentication flows in external browsers or in app-browser tabs such as Safari View Controller (iOS) and Chrome Custom Tabs (Android).

Overview

URLhttps://<oidc-baseurl>/precheck/auth
Request

GET with URL query parameters

POST is not supported

AuthenticationNone
Success response303 See Other with response elements added to redirect uri
Error response

303 See Other with standard error response elements added to redirect uri

 Other applicable http error code if redirect uri is missing, invalid or mismatching

ExampleSee below

The recommended practice for merchants is to use the Authorize URL from Openid-configuration rather than hardcoding the above URL value.


Request parameters

NameDescription
scopeList of scope values specifying what kind of resources (dataset) the OIDC Client requests access to. The value openid must always be included in the list. Each scope value must be separated by space. Scope values are case-sensitive.
response_type

Determines the message flow to be used, thus also governing the content and type of the response from the Authorize endpoint. The following combinations are supported:

Note: Other response types such as "id_token", "id_token token" and "code token" was previously supported.

code_challenge

Base64-URL-encoded string of the SHA256 hash of a "code verifier" value generated on merchant side. A code verifier is a cryptographically random string using the characters A-Z, a-z, 0-9, and the punctuation characters -._~ (hyphen, period, underscore, and tilde), between 43 and 128 characters long.

code_challenge_method
  • S256
client_idUnique ID (arbitrary string) for the OIDC Client in question. This is created as part of the provisioning process.
redirect_uriRedirect URI to which the Authorize response will be sent. This URI must exactly match one of the Redirect URI values for the OIDC Client pre-registered at the OpenID Provider
state Opaque value used to maintain state between the request and the callback. It is strongly recommended that merchants provide this value to mitigate Cross-Site Request Forgery.
response_mode

The response mode to be used for returning parameters from the Authorization Endpoint via redirect_uri. The following values are supported:

  • query
  • fragment
  • form_post
nonce String value used to associate a ODIC Client session with an ID Token, and to mitigate replay attacks. The value is passed through unmodified from the Authentication Request to the ID Token
ui_localesMay be used to set a language preference for GUI handling. The default GUI experience supports 'nb' (Norsk Bokmål) and 'en' (English). If ui_locales is not set, the first (if any) Accept-Language header of the request is used to dermine preferred locale. Otherwise 'nb' is used by default.
promptSupport for the standardized values none and login. The former can be used to check for an existing (still valid) authentication session with the OIDC provider. The latter can be used to force a re-authentication, possibly with a different login_hint and/or acr_values.
acr_values

Requests use of specific Identity provider (IDP), or any IDP at a given Level of Assurance (Authentication Context Class Reference) or above. A selector dialogue is shown to the enduser if more than one IDP option meet the required minimum level. Note that this parameter has no effect if the login_hint parameter contains a reference to any particular IDP. Nor does it have any effect if the id_token_hint parameter is set. If none of these parameters are set a selector dialogue is shown containing all available IDP options. Remark that some IDPs may only be selected using login_hint

Examples:

urn:bankid:bim urn:bankid:bid
A choice of both BIM and BID are presented to the end user. Note: space separated list
4
Any IDP with LoA >= 4 


login_hint

This parameter may be used to specify the use of any particularly named IDP (Authentication Method Reference) along with any pre-configuration for the designated IDP. Note that this parameter has no effect if the id_token_hint parameter is set. If none of these parameter are set, the acr_values parameter determines IDP selection. If login_hint contains personal information, it should be encrypted, see details in Signing and encryption. Remark that some IDPs may only be selected using login_hint.

See further details on login_hint support for each of the supported IDPs. 

display

The display parameter allows Clients to adjust the user interface displayed to end-users to make it more consistent with the device type and viewport size.

  • page  (default) - displays a responsive consistent with a full User Agent page view (desktops, tablets). If the display parameter is not specified, this is the default display mode. 
  • touch  - displays the user interface consistent with a device that leverages a touch interface and is more suited for integration in mobile apps.
  • wap  - same as touch  above.
  • popup - displays the user interface consistent with a popup or framed User Agent window.
id_token_hintJWT value for an ID Token previously issued by the OIDC Provider used as a hint about the enduser's authenticated session with the OIDC provider. Note that this parameter has precedence before both acr_values and login_hint, but precedence after the prompt parameter. If the ID Token has expired, a new authentication is triggered for the IDP option that was used when the ID Token was issued. Otherwise the authentication is still granted valid and the OIDC Provider proceeds directly to consent handling.

request

This parameter may be used to group and send several query parameters as one. The standard specifies guidelines how to use it. BankID OIDC supports both plaintext and encrypted request objects. Encrypted and signed objects are in certain cases possible. If the request parameter contains personal information it should be encrypted, see details in Signing and encryption. The request_uri parameter is not yet supported.
api_version
Provide the desired version of BankID OIDC. Integer value. See list of available versions.

Note that the following set of standard parameters is currently not supported by the OpenID Connect Provider from BankID: max_age,request_uri

Example request

GET authorization_endpoint
 ?client_id=myclient-bankid-current
 &scope=openid+profile
 &redirect_uri=https%3A%2F%2Fmywebapp.example.org%2Fcallback
 &response_type=code
 &state=01e3ac8e-4a26-4dfb-79ca-2631394c4144
 &nonce=1fb72f68-1bea-2ba2-12d7-24df1c999d1b
 &code_verifier=G2stUpTWHiWMJEeFaH1IJkiCD23BOqCi8tF6cPSE1d8
 &code_challenge_method=S256

Response elements

Authorization Code flow

The standard response  for this flow is to add relevant parameters as URL query-parameters to the redirect_uri, unless a different response_mode was specified.

If the authentication was successful, the response contains a code parameter that may be used to retrieve an ID token and Access token from the token endpoint. If the authentication was unsuccessful, an error, and potentially an error_description, will be returned. See authentication error response for more details. The response may also contain a state parameter if it was specified when initiating the authentication.

NameDescription
stateThe state parameter should be used by the merchant to correlate the initial request and the callback response. It will only be included if provided in the initial request.
session_stateBankID OIDC does not support session management, but this parameter may still be included in the response. It should be ignored by merchants. 
codeA short-lived, one time use code that is used to retrieve the ID, Access and Refresh tokens using the token endpoint.

Example response


https://util.bankidnorge.no/oidc-testclient/callback
 ?state=01e3ac8e-4a26-4dfb-79ca-2631394c4144b
 &session_state=12801cef-7746-4dd6-a418-43bda5c7002a
 &code=aa47ea38-633d-4e9a-bd41-4f1a5b50fe7c.66801cef-7746-4dd6-4391-43bda5c7002b.0ab47fe7-0376-4b80-b217-065f5a5a3760