The PAR endpoint (Pushed Authorization Request)

The PAR endpoint is available at the path /connect/par relative to the authority. For instance, the PAR endpoint in the test environment will look like this:

https://helseid-sts.test.nhn.no/connect/par

The usage of this endpoint is described here.

The Par endpoint is used when a Client does a POST request to HelseID in order to retrieve a request_uri parameter for use against the Authorize endpoint. All the parameters used against the Authorize endpoint are accepted, including PKCE, Resource Indicators, and OpenID Connect with HelseID specific parameters.

⚠️  Usage of the PAR endpoint

Be advised that for new Clients that wants to log on a user, the use of the PAR endpoint is mandatory as described in the security profile for HelseID.

Requests to the PAR endpoint

The following parameters are required:

  • client_id: An identifier for the Client. You will receive this value from HelseID Selvbetjening.
  • scope: One or more scopes, separated by spaces, as described here [OAuth 2.0] and here [OpenID Connect]
  • redirect_uri: This value must be an exact match against any redirect URI set up in HelseID Selvbetjening
  • response_type: This value must always be code (other flows, such as Implicit or Hybrid are not allowed)
  • code_challenge: This is the code challenge for the use of PKCE
  • code_challenge_method: The method used for the code challenge. The value must be S256.
  • client_assertion: A base64 encoded JWT signed with your private key, as described here
  • client_assertion_type: The type of the client assertion. The value must be urn:ietf:params:oauth:client-assertion-type:jwt-bearer.

The following parameter is recommended:

  • state: HelseID will echo back the state value in the Token response. This can be used for round tripping state between client and provider, correlating request and response and CSRF/replay protection.

The following parameters may be used:

  • resource: The value of this parameter is one or more registered API resources. If multiple resources are posted, a token request must be made later for each resource. The purpose of this parameter is to simplify the process of getting Access Tokens with single audiences.

  • request: Instead of providing all parameters as individual query string parameters, you can provide a subset, or all of them in a signed JWT. The signed JWT can also be used for providing an authorization_details object that can contain information about organization numbers and/or nhn:tillitsrammeverk:attest. The JWT must be signed with the same private key that is used for client authentication (client_assertion above).

  • prompt: You can use the following value:

    • login The login UI will be shown, even if the user is already signed-in and has a valid session

  • nonce: HelseID will echo back the nonce value in the Identity Token

An example of content when using the PAR endpoint:

 POST /connect/par HTTP/1.1
 Host: helseid-sts.nhn.no
 Content-Type: application/x-www-form-urlencoded

 client_id=973f112f-47e5-4fb2-b211-43c242b7fce0&
 scope=openid%20profile%20nhn%3Ahelseid-public-samplecode%2Fauthorization-code&
 redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb
 response_type=code&
 state=duk681S8n00GsJpe7n9boxdzen&
 code_challenge=jVtDOI4ss7|YHwEOuOf1jFOJVg563bBMF65FBIQ453w&
 code_challenge_method=S256&
 client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer&
 client_assertion=eyJraWQiOiI0Mi...BV9rRG-3eI1Ksh0kQ1CwvzA

Response from the PAR endpoint

A successful response from the PAR endpoint contains two parameters in the body:

request_uri: A value that corresponds to the parameters sent in the request to the PAR endpoint. This value is used fof user logon via the Authorize endpoint.

expires_in: A value that represents the lifetime of the request URI in seconds as a positive integer. This lifetime is normally 600 seconds.

Error responses

The PAR endpoint returns error responses in the same format as the Token endpoint, or the Authorization endpoint. See this document for more information.