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

 

⚠️

Important

The code_verifier must be retained until the authorization code is exchanged for a token.
If it is overwritten or does not match the code_challenge used 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

ParameterLocationRequiredType/FormatDescription
AuthorizationHeaderYesHTTP BasicOAuth client authentication. Base64-encoded UTF-8 value of client_id:client_secret
ContentTypeHeaderYesStringapplication/x-www-form-urlencoded
response_typeFormYesStringStatic value code
client_idFormYesStringSame client_id used for Basic authentication
redirect_uriFormYesURIPreviously registered callback URL
scopeFormYesStringStatic value credential
stateFormYesString, preferably randomCorrelation and CSRF protection value
signatureQualifierFormYesStringStatic value eu_eidas_qes
acr_valuesFormRecommendedStringRestricts 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_methodFormYesStringStatic value S256
code_challengeFormYesBase64URL without paddingSHA-256 hash of the generated code_verifier

Supported acr_values Values

User Flowacr_values ValueDescription
eID Card on Desktopurn:eparaksts:authentication:flow:sc_pluginAuthentication using a physical eID card, smart card reader, and eID/smart card software
eID Scanurn:eparaksts:authentication:flow:mobile-eideID Scan authentication flow on a mobile device
ℹ️

Note

The acr_values parameter 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
}
ParameterTypeDescriptionIntegrator Action
request_uriStringOne-time reference to the PAR requestStore and URL-encode when constructing the authorize_url
expires_inNumberValidity period of the request_uri in secondsAuthorization 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.

ParameterConditionDescriptionIntegrator Action
codeSuccessful authorizationSingle-use authorization codeStore temporarily and immediately exchange it for a token
stateIf included in the requestOriginal state valueMust be validated against the stored state value from the PAR request
errorAuthorization failedOAuth error codeDo not perform token exchange
error_descriptionAuthorization failedError descriptionDisplay 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

ParameterLocationRequiredType/FormatDescription
AuthorizationHeaderYesHTTP BasicOAuth client identifier and secret
Content-TypeHeaderYesStringapplication/x-www-form-urlencoded
grant_typeFormYesStringStatic value authorization_code
client_idFormYesStringOAuth client identifier
codeFormYesStringSingle-use code received via the callback
redirect_uriFormYesURISame value used in the corresponding credential PAR request
code_verifierFormYes43–128 PKCE charactersThe 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

ParameterTypeDescriptionIntegrator Action
access_tokenStringShort-lived Bearer access tokenStore only in memory or a protected temporary storage location; use for credentials/info requests.
token_typeStringToken typeVerify that the value is Bearer.
expires_inNumberToken validity period in secondsRequests using the token must be completed before expiration.
authorization_detailsArrayGranted authorization contextVerify the expected sign_identity_registration type and qualifier group.
credentialIDStringNewly created short-term credential identifierStore as credential_id for subsequent requests.

Did this page help you?