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.

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 (audiences). If multiple resources are posted, the client can make a Token request for each resource at a later stage. The purpose of this parameter is to simplify the process of obtaining an Access Token for an API resource.

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

• acr_values: which IDPs that can be offered for a user

• 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

• response_mode: Can be used to send response parameters from HelseID into the client's browser via the HTTP POST method. See OAuth 2.0 Form Post Response Mode.

If you need to attach an organization number, SFM-id and/or Tillitsrammeverk in the PAR endpoint

You can use a Request object for this, but in most cases, it will be convenient to submit organization numbers, SFM-id, and/or Tillitsrammeverk in the Token endpoint.

Typically, the client will not know who the user is until they have logged in. Since a Request object must be sent via the PAR endpoint, this means that the client must perform two user logins against HelseID if they are to send organizational information this way. Therefore, it is more convenient to use the Token endpoint for this, by using the refresh_token flow, for example with the use of organization numbers.

If you still don't have the option to use the Token endpoint for this, you may use the request parameter:

• request: Instead of putting all parameters in the call as simple string parameters, you can put all parameters in a signed JWT. The exception is the parameters client_assertion, and client_assertion_type, which must be put in the body. The signed JWT object can also be used to attach organization numbers. The JWT object must be signed with the same private key that is used for client authentication (client_assertion above).

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&
 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&
 state=CfDJ8LVCUUdmXXVMi6H...HHDM86inxQaXb4eBLma8REL&
 resource=nhn%3Apersontjenesten&
 resource=nhn%3Akjernejournal

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