Skip to content

Pushed Authorization Request (PAR)

The Pushed Authorization Request (PAR) is a method for the client to send the authorization request parameters to the OIDC Provider server in a backchannel request.

This is useful for several reasons:

  • The client can send sensitive information directly to the authorization server, without exposing it to the user agent.
  • The OIDC Provider can ensure that the request parameters is not tampered with. E.g. when using private_key_jwt the JWT signature can be verified.
  • URL length limitations are avoided, as the request is sent in the body of the request.

Steps

  1. The client sends a backchannel request with the standard authorization parameters to the OIDC Provider.
  2. The OIDC Provider validates the request and returns a reference to the client.
  3. The client sends the reference to the user agent through the regular Authorize request.
  4. The Authorization Code flow continues as normal and end-user authenticates...

API

Note

You will always find the up-to-date URL for the PAR endpoint in the OpenID Configuration - as pushed_authorization_request_endpoint.

1. Create Pushed Authorization Request

Request

POST [pushed_authorization_request_endpoint]
Headers
Content-Type: application/x-www-form-urlencoded
Authentication

Client authentication according to supported methods.

Body

The body of the request contains the parameters of the authorization request, form encoded.

client_id=myclient-bankid-current
&scope=openid+profile
&redirect_uri=https%3A%2F%2Fmywebapp.example.org%2Fcallback
&response_type=code
&login_hint=:12345678901
&acr_values=urn:bankid:bid
&state=01e3ac8e-4a26-4dfb-79ca-2631394c4144
&nonce=1fb72f68-1bea-2ba2-12d7-24df1c999d1b
&code_challenge=rMU4NcLC3_O_tsTZ3gQE1ONoXD6OMZph_2zRuobajhQ
&code_challenge_method=S256
Parameters

The content of the body parameters is the same as authorize parameters.

Name Description
client_id Unique ID (arbitrary string) for the OIDC Client in question. This is created as part of the provisioning process.
redirect_uri Redirect 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.
scope List 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. Only code (Authorization code flow) is supported.
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.
acr_values Allows you to determine the a Level of Assurance (LoA) and ACR (Authentication Context Class Reference) value by selecting the Identity provider (IDP) used for authentication. The value is a space-separated list of ACR values, and we support the following values:

- urn:bankid:bis - Biometric authentication using WebAuthn at LoA 3.
- urn:bankid:bid - Authentication using BankID at LoA 4.

If none of these parameters are set, the default LoA is 4 (BankID High).

Note: 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.
login_hint

(request objects/PAR only)
This parameter can be used to prefill the user ID in the login form. The value is a colon (:) followed by NNIN (Norwegian National Identity Number).

Example: :01010112345

Do not send login_hint as query parameter. Use PAR or encrypted request objects.

Note: Previously, login_hint was used to select IDP or LoA; you should instead use the acr_values parameter for that purpose. Warning: Specifying nnin in an unencrypted query param login_hint is deprecated in API Version 4.
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 Method used to encode the code verifier. Only "S256" (SHA256) is supported.
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.
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 resulting ID Token as nonce claim.
api_version The version of the API of the BankID OpenID Provider to be used. Integer value. See API versions for more information.
ui_locales May be used to set a language preference for GUI handling. The default GUI experience supports: nb (Norsk Bokmål), nn (Norsk Nynorsk) and 'en' (English). If ui_locales is not set, the first (if any) Accept-Language header of the request is used to determine preferred locale. Otherwise nb is used by default.
prompt Support 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. Optional.
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. We support:

page (default) - standard responsive view (desktops, tablets).
touch - suitable for integration in mobile apps.
wap - same as touch above.
popup - suitable for popup or iframe integrations.
request This parameter may be used to group and send several query parameters as one. The standard specifies guidelines on how to use it. BankID 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 encryption.
request_uri Only supported when using with Pushed Authorization Requests (PAR) to reference previously pushed request parameters.
id_token_hint JWT value for an ID Token previously issued by the OIDC Provider used as a hint about the end user's existing 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 first issued. Otherwise, the authentication is still valid and the OIDC Provider proceeds directly to consent handling.

Response

Status
201 Created
Headers
Content-Type: application/json
Body

The response is a JSON structure containing the reference to the request object.

{
  "request_uri": "urn:ietf:params:oauth:request_uri:12627496-8a05-4e3d-a04c-9478fc9c456b",
  "expires_in": 300
}

2. Authorization Request with Request URI

Start end-user BankID authentication by redirecting the user to the below URL:

Request

GET [authorization_endpoint]
?client_id=myclient-bankid-current
&request_uri=urn:ietf:params:oauth:request_uri:12627496-8a05-4e3d-a04c-9478fc9c456b

Response

After BankID authentication, we will return the end-user to the redirect_uri you specified in the initial request.

This is following the Authorization Code flow.

3. Token exchange

Do the token request for grant_type=authorization_code.