Step 1: Create a Signing Credential
To create a Qualified Electronic Signature (QES), a short-term signing credential must first be created.
The signing credential is created after successful user authentication and authorization.
As a result of the process, the following values are obtained:
- an access token (
access_token); - a signing credential identifier (
credentialID).
Process Overview
flowchart TD A[PKCE Preparation] B[PAR Request] C[User Authentication] D[Authorization Code] E[Access Token + Credential ID] A --> B B --> C C --> D D --> E
PKCE Preparation
Before sending the authorization request, PKCE parameters must be generated.
A random code_verifier is created, from which the code_challenge is calculated.
When creating a signing credential, the following values must be used:
code_challenge = BASE64URL_NO_PADDING(SHA-256(ASCII(code_verifier)))
code_challenge_method=S256
ImportantThe
code_verifiermust be retained until the authorization code is exchanged for a token.
If it is overwritten or does not match thecode_challengeused in the PAR request, the token endpoint will return:
invalid_grant
invalidCodeVerifier
PAR Request
This request registers an OAuth authorization request on the server for obtaining a new short-term signing credential. The response returns a request_uri, which is subsequently used in browser-based authorization.
The signing credential creation process is initiated using a Pushed Authorization Request (PAR).
Endpoint
POST {{csc_base_url}}/oauth2/pushed_authorize
Authorization: Basic BASE64(client_id:client_secret)
Content-Type: application/x-www-form-urlencoded
response_type=code
client_id={{client_id}}
redirect_uri={{redirect_uri}}
scope=credential
state={{oauth_state}}
signatureQualifier={{signature_qualifier}}
acr_values={{acr_values}}
code_challenge_method=S256
code_challenge={{code_challenge}}
Input Parameters
| Parameter | Location | Required | Type/Format | Description |
|---|---|---|---|---|
Authorization | Header | Yes | HTTP Basic | OAuth client authentication. Base64-encoded UTF-8 value of client_id:client_secret |
ContentType | Header | Yes | String | application/x-www-form-urlencoded |
response_type | Form | Yes | String | Static value code |
client_id | Form | Yes | String | Same client_id used for Basic authentication |
redirect_uri | Form | Yes | URI | Previously registered callback URL |
scope | Form | Yes | String | Static value credential |
state | Form | Yes | String, preferably random | Correlation and CSRF protection value |
signatureQualifier | Form | Yes | String | Static value eu_eidas_qes |
acr_values | Form | Recommended | String | Restricts which authentication methods are offered to the user. For this service, use the eID Card and/or eID Scan flows. Multiple values are separated by a pipe character | (URL-encoded as %7C) |
code_challenge_method | Form | Yes | String | Static value S256 |
code_challenge | Form | Yes | Base64URL without padding | SHA-256 hash of the generated code_verifier |
Supported acr_values Values
acr_values Values| User Flow | acr_values Value | Description |
|---|---|---|
| eID Card on Desktop | urn:eparaksts:authentication:flow:sc_plugin | Authentication using a physical eID card, smart card reader, and eID/smart card software |
| eID Scan | urn:eparaksts:authentication:flow:mobile-eid | eID Scan authentication flow on a mobile device |
NoteThe
acr_valuesparameter determines which authentication methods are offered to the user during authorization. You may specify either one or both supported authentication methods.
Response Example
{
"request_uri": "urn:ietf:params:oauth:request_uri:5a56e939-12e9-43be-8d3a-10491841edc3",
"expires_in": 60
}| Parameter | Type | Description | Integrator Action |
|---|---|---|---|
request_uri | String | One-time reference to the PAR request | Store and URL-encode when constructing the authorize_url |
expires_in | Number | Validity period of the request_uri in seconds | Authorization must be initiated before expiration |
The authorize_url is constructed as follows:
{{csc_base_url}}/oauth2/authorize
?client_id={{client_id}}
&request_uri=<URL-encoded request_uri>User Authorization
Open the authorize_url in the user's browser so that the EIDAS platform can authenticate the user and approve the creation of the signing credential.
The acr_values parameter specified in the PAR request determines which authentication flow is presented to the user. If both supported authentication methods are specified, the user can choose between an eID Card and eID Scan. If only one method is specified, the authorization server redirects the user directly to that authentication scenario.
Callback Parameters
After successful authorization, the platform redirects the browser to the redirect_uri with the callback parameters.
| Parameter | Condition | Description | Integrator Action |
|---|---|---|---|
code | Successful authorization | Single-use authorization code | Store temporarily and immediately exchange it for a token |
state | If included in the request | Original state value | Must be validated against the stored state value from the PAR request |
error | Authorization failed | OAuth error code | Do not perform token exchange |
error_description | Authorization failed | Error description | Display an appropriate error message |
Authorization Code Exchange
This request exchanges the authorization_code received through the browser callback, together with the corresponding PKCE code_verifier, for a short-lived bearer token and a credentialID.
HTTP Request
POST {{csc_base_url}}/oauth2/token
Authorization: Basic BASE64(client_id:client_secret)
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code
client_id={{client_id}}
code={{authorization_code}}
redirect_uri={{redirect_uri}}
code_verifier={{code_verifier}}
Input Parameters
| Parameter | Location | Required | Type/Format | Description |
|---|---|---|---|---|
Authorization | Header | Yes | HTTP Basic | OAuth client identifier and secret |
Content-Type | Header | Yes | String | application/x-www-form-urlencoded |
grant_type | Form | Yes | String | Static value authorization_code |
client_id | Form | Yes | String | OAuth client identifier |
code | Form | Yes | String | Single-use code received via the callback |
redirect_uri | Form | Yes | URI | Same value used in the corresponding credential PAR request |
code_verifier | Form | Yes | 43–128 PKCE characters | The same verifier used to generate the PAR code_challenge |
Response Example
{
"access_token": "<access_token>",
"token_type": "Bearer",
"expires_in": 120,
"authorization_details": [
{
"type": "sign_identity_registration",
"group_labels": [
"urn:csc:signatureQualifier:eu_eidas_qes"
]
}
],
"credentialID": "<credential_id>"
}
Response Parameters
| Parameter | Type | Description | Integrator Action |
|---|---|---|---|
access_token | String | Short-lived Bearer access token | Store only in memory or a protected temporary storage location; use for credentials/info requests. |
token_type | String | Token type | Verify that the value is Bearer. |
expires_in | Number | Token validity period in seconds | Requests using the token must be completed before expiration. |
authorization_details | Array | Granted authorization context | Verify the expected sign_identity_registration type and qualifier group. |
credentialID | String | Newly created short-term credential identifier | Store as credential_id for subsequent requests. |
Updated about 2 months ago