Page tree
Skip to end of metadata
Go to start of metadata

Guidelines for electronic identification and Remote signing integration (Integration platform)

Scope

Those guidelines are intended for LVRTC partners who want to integrate in their solution LVRTC provided electronic identification and remote signature signing with keys operated by LVRTC on behalf of end-user protected by eParaksts Mobile authentication mobile application. The primary audience is developers and system architects.

Termini un abreviatūras


Term, Abbreviation

Explanation

API

Application Programming Interface

base64

A group of binary-to-text encoding schemes that represent binary data in an ASCII string format by translating it into a radix-64 representation.

eIDAS

The European Parliament and of the Council of Regulation (EU) No 910/2014 “On electronic identification and trust services for electronic transactions in the internal market and repealing Directive 1999/93/EK”, on July 23 2014.

end-user

Subscriber of LVRTC provided electronic identification and electronic signature services. Manages LVRTC issued smartcard and/or eID card and/or eParaksts Mobile with related signing identity.

GET

HTTP request method

hash

One-way repeatable mathematical data transformation that identifies a raw data set with a fixed length symbol string.

HTTP

Hyper Text Transport Protocol

HTTPS

Hyper Text Transfer Protocol Secure

Integration platform

LVRTC provided platform – acting as Identity and electronic signature services provider

JSON

JavaScript Object Notation.

LVRTC

LV – VAS „Latvijas Valsts radio un televīzijas centrs”
EN – State Joint stock company “Latvian State Radio and Television Centre”

OAuth2.0

User authentication and authorization standard

PAdES

PDF advanced electronic signature/seal standard

PDF

Portable Document Format

PIN

Personal identification number.

PKCS #1

Public-Key Cryptography Standard describing usage of RSA in electronic signature.

POST

HTTP request method

Service provider

External service provider who integrates with "Integration platform" and receives electronic identification and remote signing services

sha1, sha256, sha384, sha512

Hash algorithms.

SSO

Single Sign-On

URL

Uniform Resource Locator

UTF-8

Text encoding

XAdES

XML advanced electronic signature/seal standard

XML

Extensible Markup Language

Integrācijas platformas komponentes

Authorization Server

An OAuth 2.0 authorization server (AS) provides access tokens to the Service provider's applications so they can access the Web resources of Integration platform. The authorization server only issues access tokens in the following cases:

  • The owner of the Web resource authorizes the Service provider's application to access the resource.
  • The Service provider's application is the owner of the Web resource it is requesting to access.
  • The Service provider's application has administrative permissions for accessing the Web resource.

The authorization servers also validate the access tokens that the Service provider's applications include as an authorization method in the requests sent to the Integration platform services.

Access Token

An access token is a credential that demonstrates authorization for performing one or more actions on a Web resource during a determined period of time.

Identity Provider

An identity provider (IdP) authenticates the identities of the end-users of a domain. OAuth 2.0 authorization servers use an IdP to authenticate a end-user prior to prompting the end-user to authorize an Service provider's application's access to their resources.

When an authentication process finalizes, the end-user has a session in the identity provider containing their identity data, the level of authentication reached and details of the authentication process, e.g., the authentication methods used. With this information, the IdP can decide, in subsequent authentication processes, whether to directly apply single sign-on or to execute additional authentication methods.

User Information Provider

The end-user information provider (UserInfo) is an OAuth 2.0 resource server that provides reliable information on the identity of the end-users authenticated by Integration platform.

Electronic Signature Provider

The electronic signature provider (eSigP) is an OAuth 2.0 resource server that provides reliable information on the signing identities of the end-users and access to digital signature generation using the keys for these identities. It also provides basic signing identity and signature device management services.

Access to the services of the eSigP is performed via a REST API. Authorization is performed by the authorization server via OAuth 2.0.

Signing Identity

A signing identity is a set of data handled by Integration platform for managing the selection and use of a specific signature key. Each signing identity contains information on the end-user who owns the key, the X.509 certificate associated to this key and the labels that allow them to be selected.

LVRTC manages a signing identities on a server. In this case the signature key is in an HSM that the eSigP has access to The signature key is in a Thales HSM device accredited as a qualified electronic signature/seal creation device and it requires submitting a password that only that HSM can validate, the signing identity corresponding to the key in question is said to be a qualified server signing identity.

Enabling Server Signing Identities

Enabling a server signing identity is how the signature key associated to the identity is made available for generating an electronic signature. The Electronic signature provider signing identity enabling mechanism requires authentication through the submission of an access token. This access token must have the authorization of the identity's owner for using the signature keys of all the server signing identities that the subject owns in a particular schema. If the server signing identity is a qualified signing identity, the following additional conditions must be met for it to be enabled:

  • The access token presented is associated to the server signing identity corresponding to the signature key. Thus, only this signing identity can be enabled; not any other that the owner has in the same schema.
  • The access token is associated to specific data. Thus, the enabling occurs only so this data can be signed; not for the signing of any other data.
  • The enabling password of the signature key that only the Thales HSM can validate is submitted.

eParaksts Mobile

eParaksts Mobile is an application for iOS and Android mobile devices for generating electronic signatures. These signatures are used for Identity authentication: eParaksts Mobile generates the XAdES signature on a ticket that acts as a challenge that the end-user uses to prove their identity.

The cryptographic keys used to generate the signatures are stored in the mobile device in which the eParaksts Mobile app is installed. Access to these keys is protected by PIN or fingerprint. This guarantees, with a high level of trust, that the signature keys used by eParaksts Mobile are always under the exclusive control of the signer.

The signatures generated by eParaksts Mobile always require explicit approval from the end-user and are generated on the request of any set of applications the end-user accesses either with the same mobile device in which eParaksts Mobile is installed or a different one. These applications never interact directly with eParaksts Mobile but rather do so via eSigP or another application that communicates with eSigP (e.g., eSignSP).


 Integrācijas platformas pamatinformācija 

The Service provider's application must use the API Key as an authentication credential in each request it sends to the authentication and authorization service to obtain an access token for any of the resources protected by the platform. To do this, as per the OAuth 2.0 specification, the Service provider's application must put the API Key in the Authorization header of these requests as follows:
Authorization: Basic <API-Key>

API Access Key basics

Before Service provider access Integration platform API, LVRTC shall register Service provider as customer of Integration platform. After signing a contract with LVRTC (Test of Production environment) LVRTC generates Service Provider’s application identifier – (client_id) and shared secret (client_secret), intended for the customer usage.
API Access Key (API Key) is generated from the Service provider’s application  identifier (client_id), a secret shared with the platform (client_secret)  on the following basis:

Service provider's application identifierclient_id are converted using the UTF-8 character encoding and URL encoding conditions.

(warning)  For example, value "Portāls" conversion result is "port%C4%81ls".

Service provider's application password client_secret is converted by using the UTF-8 character encoding and URL encoding conditions.

(warning)  For example, value "drošība" conversion result is "dro%C5%A1%C4%ABba".

Both values of the previous two steps must be combined with separator colon “:” between them.

(warning)  For example, by using previous examples, the result will be "port%C4%81ls:dro%C5%A1%C4%ABba".

Obtained value must be converted using base 64 encoding without line breaks.

(warning)  For example, values "port%C4%81ls:dro%C5%A1%C4%ABba" conversion result is "CG94ydCVDNCUMWxzOmRybyVDNSVBMSVDNCVBQmJh".

"MIME Tools" tool in "Notepad++" can be used for this purpose.

API-Key = base64[url_encode(utf8(<client_id>)) ':' url_encode(utf8(<client_secret>))]


API Authorization Calls

To make API calls from authorization server it is necessary to get API access token which is according to the OAuth 2.0 request flow and consists of two steps:
• API authorization code request.
• API access token request.
If it is necessary to get the end-user approval for obtaining the authorization code then authorization server redirects end-user browser to identity provider to perform end-user authentication. If at this point the end-user has not been authenticated, browser displays a login page for the end-user with possible logon methods (smart cards or eParaksts Mobile) or, if service provider make redirect for specific logon method (smart cards or eParaksts Mobile), end-user are redirected to specific logon process. If the end-user is already authenticated and identity provider supports single login (single sign-on), the login page is not displayed again and the operation is approved automatically.
The authorization server issue the Bearer type OAuth 2.0 access tokens and its access rights is provided by authorization code request with specified scope.
To make API calls with this authorization method in accordance to OAuth 2.0 specification, access token API calls must be added as HTTP request header Authorization attribute.

Authorization: Bearer <token>

To control the Service provider’s application access to requested service, access tokens are validated in each API call. Each validation includes token expiration time, identity of the domain and associated scope. In order to avoid a situation when an expiration time of token has expired it is recommended before each API call require a new token.


OAuth2.0 konfigurācija

Basic parameters for OAuth 2.0 Service Configuration

Parameter

Description

Integration platform
domain name {Host}

URL for authentication and authorization requests

Test environment: eidas-demo.eparaksts.lv

Production: eidas.eparaksts.lv

Client_ID

Service provider ID generated by LVRTC

Client_secret

Service provider Access Password generated by LVRTC

Scopes

urn:lvrtc:fpeil:aa – For electronic identification

urn:lvrtc:fpeil:aa:age – For electronic identification with age parameter (Restricted access, contact LVRTC for more information.)

urn:safelayer:eidas:sign:identity:profile – to get signing identity

urn:safelayer:eidas:sign:identity:use:server – to request signature from the HSM.

Authorization Endpoint

https://{Host}/trustedx-authserver/oauth/{as}?

response_type=code&
client_id=...&
state=...&
redirect_uri=...&
scope=...&
prompt=...&
acr_values=...&
ui_locales=...

Access Token Endpoint

https://{Host}/trustedx-authserver/oauth/{as}/token

Important! Refresh token functionality is not supported, the expired session must be restored using the full authentication process.

User Info Endpoint

https://{Host}/trustedx-resources/openid/v1/users/me

{as}

lvrtc-eips-as (for authentification only)

lvrtc-eipsign-as (for authentification and access to signing services)


OAuth2.0 Autorizācijas API

The OAuth 2.0 authorization model allows a Service provider's application to obtain access to a HTTP service or resource, either on behalf of the end-user who owns the resource or on behalf of the Service provider's application itself. To do this, the Service provider's application obtains an access token via the following operations:

API authorization code request.

API access token request.

Autorizācijas koda saņemšana

Description

This operation entails performing an authorization code grant type OAuth 2.0 request request.  In contrast to the other Integration platform APIs (except SignAPI), the messages of this operation are not exchanged directly between the Service provider's application and Integration platform but rather indirectly via the end-user's browser using browser redirects.

This operation lets an Service provider's application obtain authorization from the end-user for accessing one of their resources or their identity data. The end-user's authorization is obtained via an authorization code credential. The authorization code is sent via the browser as a response from the operation. The Service provider's application exchanges the authorization code for the corresponding access token for accessing the resource.

Request

To start the authorization code grant flow, the Service provider's application directs the end-user's browser to one of Authorization server /trustedx-authserver/oauth/ endpoints. As a result of this redirect, the browser sends an HTTP request like the following, which corresponds to the OAuth 2.0 authorization request message. The request must be sent by TLS and use the GET method.

GET /trustedx-authserver/oauth/{as}?response_type=code&
             client_id=...& 
             state=...&
             redirect_uri=...&
             scope=...&
             prompt=...&
             acr_values=...&
             ui_locales=...&
             sign_identity_id = ...&
             digests_summary = ...&
             digests_summary_algorithm = ...&   
Note
All the applications integrated with Integration platform authorization server via browser redirect (OAuth 2.0) must do so using a consistent base URL that has the same DNS domain name, the same port (by default, 8082) and the same Web application name (by default, trustedx-authserver). The browsers must always connect to Integration platform Authorization server using the same base address so the identity provider can maintain the sessions and apply SSO consistently.

Parameters


Name

Type

Usage

Description

as

Path

Required

Identifier of the Integration platform authorization server to which the authorization request is sent (Server ID field of one of the Authorization server entities).

Available "as" (will be specified when issuing client_id and client_secret after registration):

lvrtc-eips-as

lvrtc-eipsign-as

response_type

Query

Required

Must take the code value, which indicates that an authorization code is requested.

client_id

Query

Required

Service provider’s application identifier issued to Service provider by LVRTC

state

Query

Recommended

We recommend using this parameter to safeguard against CSRF attacks. To do this, the Service provider’s application must include a random value in this parameter, store it in the HTTP session and verify it when the Authorization Response message is received. The random value associates the authorization request with the HTTP session, which safeguards against the Service provider’s application processing an Authorization Response message not returned in response to an Authorization Request message specified previously in the end-user's browser.

redirect_uri

Query

Required

Redirect URI to the Service provider's application. The Service provider's application waits to receive at this URI the Authorization response/Authentication response message with the authorization code. It must match one of the Redirect URIs registered for the Service provider's application, or a redirect URI of the system. If the Service provider's application was configured to allow any redirect URI (not recommended), this parameter is not checked.

This parameter can be omitted if only one specific redirect URI was registered for the Service provider's application. In this case, the registered redirect URI is used.

scope

Query

Recommended

List of values, separated by spaces, that represent the scope of the authorization that the Service provider’s application wants to obtain. It queries the scopes required for accessing the resources or services in question.

Defined scopes:

urn:lvrtc:fpeil:aa – For electronic identification

urn:lvrtc:fpeil:aa:age – For electronic identification with age parameter (Restricted access, contact LVRTC for more information.)

urn:safelayer:eidas:sign:identity:profile – to get signing identity

urn:safelayer:eidas:sign:identity:use:server – to request signature from the HSM.

urn:safelayer:eidas:oauth:token:introspect – For access LVRTC provided Integration platform SignAPI service (Service provider authentication (without end-user involvement)).

prompt

Query

Recommended

The values login and none are supported:

  • The login value disables SSO, a login page is displayed (redirect) always.

  • The none value specifies that there can be no interaction with the end-user (neither for authenticating them nor for requesting their authorization).

acr_values

Query

Optional

Defines conditions for authenticating the end-user (minimum levels or specific flows) who must authorize the access.

Defined authentication methods:

  • urn:eparaksts:authentication:flow:mobileid - eParaksts mobile flow;
  • urn:eparaksts:authentication:flow:sc_plugin – Smart card flow;

If the parameter is not specified, its displays the available logon methods (end-user can choose).

ui_locales

Query

Optional

Specifies a list of languages ordered by preference. The end-user interface, available languages and settings:

  • lv – Latvian language;
  • en – English language;
  • ru – Russian language;

If the parameter is not specified, a end-user's browser language is used, if that language does not exist, then English language is used instead.

sign_identity_id

Query

Optional

(warning) This parameter must only be used to obtain the authorization from the end-user for generating a digital signature with a server signing identity enabled via password stored on the HSM. (warning)

Signing Identity received from authenticated end-user data request using urn:safelayer:eidas:sign:identity:profile scope (serverid label).

digests_summary

Query

Optional

(warning) This parameter must only be used to obtain the authorization from the end-user for generating a digital signature with a server signing identity enabled via password stored on the HSM.(warning)

Its value must be the base64 encoded cryptographic hash of the concatenation of the cryptographic hashes of the data to be digitally signed.

Value must be encoded as URL safe.

(warning)(warning)(warning) Very important! Hash value shall be recalculated with digests_summary_algorithm from signable data value, e.g. BASE64(SHA256(<signable data>))(warning)(warning)(warning)

digests_summary_algorithm

Query

Optional

(warning) This parameter must only be used to obtain the authorization from the end-user for generating a digital signature with a server signing identity enabled via password stored on the HSM.(warning)

Hash algorithm used to calculate digests_summary value (SHA256 for example)


Note
Don’t confuse the HTTP session that the application has with the browser with the security context or session the application creates or updates when the OAuth 2.0 flow finishes. The HTTP session exists previously, from the moment the browser accesses the Web application, and even though the end-user has not already authenticated. The security context is data on the authenticated end-user that the application usually stores in the HTTP session to remember that it is this end-user that is logged in to the application via the browser, and/or the OAuth access token. Just as the application does, TrustedX also keeps an HTTP session with the browser and a security context for the authenticated end-user.

Example: Authorization Request

This example shows an OAuth 2.0 authorization request message from the "Portal". The Service provider’s application requests an authorization with the "urn:lvrtc:fpeil:aa" scope to authorization server "lvrtc-eips-as" with condition the login page is displayed in the Latvian language.

GET /trustedx-authserver/oauth/lvrtc-eips-as?response_type=code&
                                   client_id=port%C4%81ls&
                                   state=1234567890&
                                   redirect_uri=https%3A%2F%2Fwww.demoapp.lv%2Foauth%2Fback&
                                   scope=urn%3Alvrtc%3Afpeil%3Aaa&
                                   prompt=login& ui_locales=lv HTTP/1.1
Host: eidas.eparaksts.lv

Example: Signature Authorization Request

Additional parameters to end-user authentication must be used to obtain the authorization from the end-user for generating a digital signature with a server signing identity enabled via password stored on the HSM (On signing procedure Server signing checks whatever signable data to be signed conform to data provided for signing).

If end-user is already authenticated with active SSO, end-user will have to enter signing (HSM) password only.

GET /trustedx-authserver/oauth/{as}?response_type=code&
           client_id=...&
           state=...&
           redirect_uri=...&
           scope=...&
           prompt=...&
           acr_values=...&
           ui_locales=...&  
           sign_identity_id=...&
           digests_summary_algorithm=...&
           digests_summary=...

Response

Once the end-user has been authenticated (or SSO applied), and the end-user has granted authorization, the Service provider’s application receives an HTTP GET request of the following type from the end-user's browser. This HTTP request is an OAuth 2.0 authorization response or an OpenID Connect authentication response. The Service provider’s application receives this request at the redirect URL specified in the authorization or authentication request message (the redirect_uri parameter of the request) or in the registered redirect URL.

GET {redirection_uri_path}?code={code}&state={state} HTTP/1.1
Host: {redirection_uri_host}


Where {redirection_uri_host}{redirection_uri_path} is the redirect URI to the Service provider’s application.


Piekļuves talona(token) saņemšana

Description

This operation obtains an OAuth 2.0 access token. This operation can be invoked as part of an OAuth 2.0 authorization code grant flow or via an OAuth 2.0 Service provider's credentials grant flow.

End-user access token

When the authorization code grant flow is used, the obtained access token represents the authorization granted by a end-user to the Service provider's application making the call for accessing certain resources or services on this end-user's behalf (identity data, signature identities, etc.). To obtain the token, the Service provider's application must present the authorization code obtained with the Obtain authorization operation.

This type access token is used to receive end-user's:

  • Electronic identification;
  • signing identities;
  • eParaksts Mobile related signing and authentication certificates;
  • PKSC#1 signature

Introspect access token

When the Service provider's credentials grant flow is used, the obtained access token demonstrates the administrative authorization of the Service provider's application making the call for accessing certain resources or services (i.e., without direct intervention of the resource's owner), or for accessing resources of the Service provider's application. Token is issued when the authorization server that processes the request is not associated to an identity provider. A token of this type can be used for accessing resources not associated to end-users or to end-user resources of any domain.

This type of access token is used to get access to Signature creation and validation service API's

Request

To obtain the token, the Service provider's application must send a request like the following to authorization server using TLS. This request is sent directly from the Service provider’s application to authorization server and does not go via the browser.

POST /trustedx-authserver/oauth/{as}/token

Parameter

Title

Type

Field

Description

as

path

mandatory

Identifier of the authorization server from which the token is requested

available "as":


Content-Type Header

Content-Type: application/x-www-form-urlencoded; charset=UTF-8

In HTTP POST request is necessary to incorporated the following main attribute: Authorization – API access token.

Authorization: Basic <API-Key>

Body

The content of the request varies according to the type of OAuth 2.0 flow in which the token is requested:

Content in the Case of the Authorization Code Grant Flow (used for electronic identification/signing requests)

Property

Usage

Description

grant_type

mandatory

Must have the authorization_code value.

code

mandatory

The authorization code received in the previous authorization response.

redirect_uri

mandatory

URI where the authorization response was received with the authorization code. Must match the redirect_uri parameter of the API authorization code request (see API authorization code request), and must be omitted if it is also omitted in the authorization request.

Content in the Case of the Client Credentials Grant Flow - Introspect access token (used for access SignAPI service)

Property

Usage

Description

grant_type

mandatory

Must have the client_credentials value .

scopemandatoryMust have the urn:safelayer:eidas:oauth:token:introspect value

Introspect access token

 Introspect access token explained...

Introspect piekļuves talona (token) saņemšana

Description

This operation obtains an OAuth 2.0 access token. This operation can be invoked as part of an OAuth 2.0 Service provider's credentials grant flow.

Introspect access token

When the Service provider's credentials grant flow is used, the obtained access token demonstrates the administrative authorization of the Service provider's application making the call for accessing certain resources or services (i.e., without direct intervention of the resource's owner), or for accessing resources of the Service provider's application. Token is issued when the authorization server that processes the request is not associated to an identity provider. A token of this type can be used for accessing resources not associated to end-users or to end-user resources of any domain.

This type of access token is used to get access to Signature creation and validation service API's

Request

To obtain the token, the Service provider's application must send a request like the following to authorization server using TLS. This request is sent directly from the Service provider’s application to authorization server and does not go via the browser.

POST /trustedx-authserver/oauth/{as}/token

Parameter

Title

Type

Field

Description

as

path

mandatory

Use "lvrtc-eipsign-as"

Host:

Test environment: eidas-demo.eparaksts.lv

Production: eidas.eparaksts.lv

Content-Type Header

Content-Type: application/x-www-form-urlencoded; charset=UTF-8


In HTTP POST request is necessary to incorporated the following main attribute: Authorization – API access token.

Authorization: Basic <API-Key>

How to generate API Access Key

 API Access Key basics...

Before Service provider access Integration platform API, LVRTC shall register Service provider as customer of Integration platform. After signing a contract with LVRTC (Test of Production environment) LVRTC generates Service Provider’s application identifier – (client_id) and shared secret (client_secret), intended for the customer usage.
API Access Key (API Key) is generated from the Service provider’s application identifier (client_id), a secret shared with the platform (client_secret)  on the following basis:

Service provider's application identifier client_id are converted using the UTF-8 character encoding and URL encoding conditions.

(warning)  For example, value "Portāls" conversion result is "port%C4%81ls".

Service provider's application password client_secret is converted by using the UTF-8 character encoding and URL encoding conditions.

(warning)  For example, value "drošība" conversion result is "dro%C5%A1%C4%ABba".

Both values of the previous two steps must be combined with separator colon “:” between them.

(warning)  For example, by using previous examples, the result will be "port%C4%81ls:dro%C5%A1%C4%ABba".

Obtained value must be converted using base 64 encoding without line breaks.

(warning)  For example, values "port%C4%81ls:dro%C5%A1%C4%ABba" conversion result is "CG94ydCVDNCUMWxzOmRybyVDNSVBMSVDNCVBQmJh".

"MIME Tools" tool in "Notepad + +" can be used for this purpose.

API-Key = base64[url_encode(utf8(<client_id>)) ':' url_encode(utf8(<client_secret>))]

Body

The content of the request for Introspect access token (used for access SignAPI service):

Property

Usage

Description

grant_type

mandatory

Must have the client_credentials value .

scopemandatoryMust have the urn:safelayer:eidas:oauth:token:introspect value

Example (Introspect access token)

The following example shows a situation in which the Service provider’s application with the identifier "Portal" and the password "drošība" authority shall transmit the request to the server with the identifier "lvrtc-eips-as":

POST /trustedx-authserver/oauth/lvrtc-eipsign-as/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Authorization: Basic CG94ydCVDNCUMWxzOmRybyVDNSVBMSVDNCVBQmJh
Host: eidas-demo.eparaksts.lv
grant_type=client_credentials&
			scope=urn%3Asafelayer%3Aeidas%3Aoauth%3Atoken%3Aintrospect

Response

In response, Integration platform authorization server issues a bearer-type OAuth 2.0 access token and returns it in a JSON structure.

{
"access_token" : {string}, 
"token_type" : "Bearer", 
"expires_in" : {number}
}

Parameter

PropertyDescription
access_token
Access token generated by Authorization server. The token has the characteristics specified in the configuration of the authorization server that processed the request and consists of a random string of the number of bytes specified in the Access token number of random bytes (by default, 32), encoded in hexadecimal.
token_type
Type of access token. Always has the "bearer" value. (Bearer type OAuth 2.0 access token).
expires_in
Lifetime (in seconds) of the access token. The Service provider’s application must perform the access the token authorizes before the token expires. This value can be configured in the Token timeout option of the authorization server (by default, 120 seconds). Once this timeout has expired, the token becomes invalid, and the Service provider’s application must obtain another one if it wants to continue invoking the protected services.

Example

Introspect access token:

HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8 
Cache-Control: no-store, no-cache, must-revalidate 
Pragma: no-cache
{
 "scope": "urn:safelayer:eidas:oauth:token:introspect",
 "access_token": "dfffb0d7f90bed142464750cacad5e4b9e23f58ecb1d77e3bdf706ba208ad16a",
 "token_type": "Bearer",
 "expires_in": 600
}



Example (end-users access token)

POST /trustedx-authserver/oauth/lvrtc-eipsign-as/token HTTP/1.1
Host: eidas-demo.eparaksts.lv
Authorization: Basic cG9ydCVDNCU4MWxzOmRybyVDNSVBMSVDNCVBQmJh
Content-Type: application/x-www-form-urlencoded; charset=UTF-8
 
grant_type=authorization_code&
   redirect_uri=https%3A%2F%2Fwww.portals.lv%2Foauth%2Fback&
   code=4515...e0ba

Example (Introspect access token)

The following example shows a situation in which the Service provider’s application with the identifier "Portal" and the password "drošība" authority shall transmit the request to the server with the identifier "lvrtc-eips-as":

POST /trustedx-authserver/oauth/lvrtc-eipsign-as/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Authorization: Basic cG9ydCVDNCU4MWxzOmRybyVDNSVBMSVDNCVBQmJh
Host: eidas-demo.eparaksts.lv
grant_type=client_credentials&
			scope=urn%3Asafelayer%3Aeidas%3Aoauth%3Atoken%3Aintrospect

Response

In response, Integration platform authorization server issues a bearer-type OAuth 2.0 access token and returns it in a JSON structure.

{
"access_token" : {string}, 
"token_type" : "Bearer", 
"expires_in" : {number}
}

Parameter

PropertyDescription
access_token
Access token generated by Authorization server. The token has the characteristics specified in the configuration of the authorization server that processed the request and consists of a random string of the number of bytes specified in the Access token number of random bytes (by default, 32), encoded in hexadecimal.
token_type
Type of access token. Always has the "bearer" value. (Bearer type OAuth 2.0 access token).
expires_in
Lifetime (in seconds) of the access token. The Service provider’s application must perform the access the token authorizes before the token expires. This value can be configured in the Token timeout option of the authorization server (by default, 120 seconds). Once this timeout has expired, the token becomes invalid, and the Service provider’s application must obtain another one if it wants to continue invoking the protected services.

Example

Access token with end-user authentication:

HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8 
Cache-Control: no-store, no-cache, must-revalidate 
Pragma: no-cache
{
"access_token" : "a2b4...6daf",
"token_type" : "Bearer", 
"expires_in" : 120
}

Introspect access token:

HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8 
Cache-Control: no-store, no-cache, must-revalidate 
Pragma: no-cache
{
 "scope": "urn:safelayer:eidas:oauth:token:introspect",
 "access_token": "dfffb0d7f90bed142464750cacad5e4b9e23f58ecb1d77e3bdf706ba208ad16a",
 "token_type": "Bearer",
 "expires_in": 600
}



Lietotāja informācijas sniedzēja API

User information provider API for Service provider’s application provides the opportunity to obtain information about authenticated end-user.


Gala lietotāja datu apjomi

The end-user data scope defines data attributes of the end-user. Each data attribute can be used in one or more end-user data scopes.

Possible data parameters:

Attribute

Description

given_name

First name

family_name

Last name

name

First name and last name

serial_number

Personal code format PNOLV-XXXXXX-XXXXX

Eips

Electronic identification service provisioning data

User information provider provides the following end-user data scopes, to be used for the request of API authorization code.

Attribute

Description

urn:lvrtc:fpeil:aa

Base data contains the following attributes:

  • given_name
  • family_name
  • name
  • serial_number
  • eips
urn:safelayer:eidas:sign:identity:profile

Obtaining of the information on the end-user's electronic signing identities.

This scope allows obtaining the sign_identities claim.

Informācijas izgūšana par autentificētu lietotāju

Description

Provides identity information and the authentication process of a end-user associated to an OAuth 2.0 authorization code grant authorization. An Service provider's application normally invokes this operation when OAuth 2.0 is used for authenticating the end-user. It doesn't normally need to be invoked when OAuth 2.0 is used only for authorization.

Request

The Service provider's application sends the following GET request using TLS:

GET /trustedx-resources/openid/v1/users/me

Authorization

The request must contain an Authorization header with an OAuth access token obtained via authorization code grant, i.e., with the approval by the end-user whose information is sought. A token obtained via a Service provider's credentials grant flow cannot be used as this type of token is not associated to a particular end-user.

Example

GET /trustedx-resources/openid/v1/users/me 
Host: eidas.eparaksts.lv
Authorization: Bearer a2b4...6daf

Response

The response is a JSON data structure that contains identity attributes of the authenticated end-user and information on the context and the authentication process (in general, claims that the identity provider makes on the authenticated subject). The claims returned depend, in the general case, on the scopes associated to the authorization used to invoke the service.

Status-Line

HTTP/1.1 200 OK

Content-Type Header

Content-Type: application/json;charset=UTF-8

Body

JSON object with the claims.

{ 
   "sub" : {string},
   "domain" : {string},
   "acr" : {string},
   "amr" : {array},
   ...
}

The following claims are always included in the response:

Property

Description

sub

Identifier of the end-user (the value of the id attribute obtained by the authentication flow applied).

domain

Identifier of the domain in which the end-user was authenticated.

acr

Authentication flow or level at which a end-user is identified (Shown only if end-user chooses logon method).

The following values are valid:

  • urn:safelayer:tws:policies:authentication:level:medium - substantial security level.
  • urn:safelayer:tws:policies:authentication:level:high – High security level.

Always make sure that the authentication flow or level corresponds to the criteria.

amr

The authentication method that the end-user has completed during the authenticated session.

The following values are valid:

  • urn:eparaksts:tws:policies:authentication:adaptive:methods:mobileid - eParaksts mobile (mobile application).
  • urn:eparaksts:tws:policies:authentication:adaptive:methods:sc_plugin – Smart card;

This property is a JSON string array.

Furthermore, the response can include other claims as per the scopes granted by the end-user:


Property

Description

{attribute1}
{attribute2}
...

Identifier of the end-user (the value of the id attribute obtained by the authentication flow applied).

sign_identities

Information on the identities of the end-user's electronic signature.

Example of response for scope urn:lvrtc:fpeil:aa

HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8 
Date: Thu, 16 Nov 2017 10:14:21 GMT
{
"sub": "ddf12735f35675ecb652e6e1a80e41f1", 
"domain": "citizen",
"acr": "urn:safelayer:tws:policies:authentication:level:high", 
"amr":["urn:eparaksts:tws:policies:authentication:adaptive:methods:sc_plugin"],
"given_name": "ANDRIS", 
"family_name": "PARAUDZIŅŠ", 
"name": "ANDRIS PARAUDZIŅŠ",
"serial_number": "PNOLV-010180-15097",
"eips": "VAS \"Latvijas Valsts radio un televīzijas centrs\""
}

Response example for urn:safelayer:eidas:sign:identity:profile scope

{"sign_identities": [
        {"id": "a46...hu6",
            "status": {
                "value": "enabled"
            },
            "labels": [
                "serverid",
                "x509:keyUsage:contentCommitment",
                "eparaksts",
                "serveridVersion1"
            ],
            "domain": "citizen",
            "links": {
                "Signatures.create.server.raw": {
                    "auth": {
                        "oauth2": {
                            "scopes": [
                                "urn:safelayer:eidas:sign:identity:use:server"
                            ]
                        }
                    }
                }
            },
            "self": "https://eidas-demo.eparaksts.lv/trustedx-resources/esigp/v1/sign_identities/a46...hu6",
            "access": [
                {"user_id": "55f...16d"
                }
            ],
            "type": "pki:x509"
        },
        {"id": "oth...516",
            "status": {
                "value": "enabled"
            },
            "labels": [
                "mobileidVersion1",
                "eparaksts",
                "mobileid",
                "x509:keyUsage:digitalSignature"
            ],
            "domain": "citizen",
            "device_id": "ae34dd7.........104a2",
            "self": "https://eidas-demo.eparaksts.lv/trustedx-resources/esigp/v1/sign_identities/oth...516",
            "access": [
                {
                    "user_id": "55f...16d"
                }
            ],
            "type": "pki:x509"
        }
    }

The User information provider returns the end-user's personal attributes and the signature identities in the data structure sign_identities.  

There is two types of signing identity, one for electronic signing and one for authentication

Authentication certificate

To receive authentication certificate, you shall read id value where labels array contains mobileid tag.

Authentication certificate is needed if you are using Sign API service for finalizing signature.

Signing certificate

To receive signing certificate, you shall read id value where labels array contains serverid tag.

Signing certificate is needed if you are using Sign API service or other solution to sign signable data according to XAdES or PAdES specification.

You also need to make sure the status value is enabled. 

The sign_identities identifier may change over time, for example, when the associated certificate expires. Therefore, when designing a solution, it should not be intended to store this identifier on the server side of the Service provider's application.

If no sign_identity (id value with the serverid tag in the labels array) is responded, then end-user has only eParaksts Mobile authentication means and need to finish onboarding for server signing solution.

In this case, you shall return message to the end-user that he has to finish onbording process for signing solution







Elektroniskā paraksta pakalpojuma sniedzēja API

The Electronic signature API generates digital signatures (PKCS #1) with the signing identities managed by the platform.

Informācijas iegūšana par identitāti no elektroniskā paraksta

There is two types of signing identity, one for electronic signing and one for authentication

Request

GET /trustedx-resources/esigp/v1/sign_identities/{sign_identity_id}

Parameters

NameTypeUsageDescription
sign_identity_id
pathRequiredIdentifier of the signing identity information is being requested on.

Authorization

The request must contain a bearer access token generated by a trusted authorization server of the service from which the information on the signing identity is requested and that is associated to the domain to which the identity belongs. This token must be used as explained in RFC 6750. It must have the urn:safelayer:eidas:sign:identity:profile scope.

Basically, the token must be included in an HTTP Authorization header as follows:

Authorization: Bearer <token>

The access token can be obtained via an authorization code grant or Service provider's credentials grant OAuth 2.0 flow.

Example

GET /trustedx-resources/esigp/v1/sign_identities/12345678 HTTP/1.1
Authorization: Bearer mF_9.B5f-4.1JqM

Response

Response body representation in JSON as follows

{
 "id" : {string},
 "self" : {string},
 "description" : {string},
 "labels" : [ {string} ],
 "type" : {string},
 "device_id" : {string},
 "domain" : {string},
 "access" : [ {
     "user_id" : {string}
 } ]
 "details" : {
      "certificate" : {string},
      "activation_mode": {string},
      "public_key" : {string}
 },
 "links" :  {
      <operation_alias> : {
           "auth" : {
               "oauth2": {
                  "scopes": [ {string} ]
               }
           }
      }    
      },
 "status" : {
    "value" : {string},
    "reason" : {string}
 }
}

Property

Description
id
Identifier of the signing identity.
self
Access URL for the signing identity.
description
Description of the signing identity.
labels[ ]

List of tags associated to the signing identity.

type
Type of signing identity. This property currently always takes the pki:x509 value.
device_id
Device where the private part of the keys associated to the signing identity is located. Only the signing identities on mobile devices have this property.
domain
Domain the signing identity belongs to.
access[ ]
Information on access control to the signing identity.
access[ ].user_id
Identifier of a end-user with access to the signing identity.
details
Details for implementing the signing identity.
details.certificate
X.509 certificate encoded in DER and base64. Only pki:x509 signing identities have this property.
details.activation_mode

Activation mode of the signing identity. Only server signing identities have this property and it can take the following values:

  • "hsm-pwd": the signature identity is activated by a password entered by the owner and validated by the HSM.
details.public_key
Public part of the keys associated to the signing identity. PublicKeyInfo ASN.1 structure encoded in DER and base64. Only pki:x509 signing identities have this property.
links
Information on operations that use the signing identity.
links.<operation_alias>
Information on the <operation_alias> operation regarding the use of the signing identity. Currently the only value possible for <operation_alias> is Signatures.create.server.raw.
links.<operation_alias>.auth
Authorization information on the <operation_alias> operation regarding the use of the signing identity.
links.<operation_alias>.auth.oauth2
OAuth 2.0 authorization information on the <operation_alias> operation regarding the use of the signing identity.
links.<operation_alias>.auth.oauth2.scopes[ ]
Set of OAuth 2.0 scopes required for accessing the <operation_alias> operation so that this operation can use the signing identity.
status
Information on the status of the signing identity.
status.value

Status of the signing identity.

  • "enabled": The signing identity is enabled.
  • "disabled": The signing identity is disabled.
  • "locked": The signing identity is locked.
status.reason
Reason why the signing identity is in its current state. This property is optional and is normally used to indicate why a signing identity has been locked or disabled.

For receiving signing certificate, labels array shall contain serverid tag.

For receiving authentication certificate, labels array shall contain mobileid tag.

Elektroniskā paraksta izveidošana serverī

Description

Creates a digital signature (PKCS #1) of data using a signing identity on server. As input, the hash of the data or a byte string to be signed raw can be received.

The signature is created with the signing identity on server specified in the request. This identity must belong to the end-user on behalf of whom the operation is performed.

Request

POST /trustedx-resources/esigp/v1/signatures/server/raw

Content-Type Header

Content-Type: application/json

Body

{
 "digest_value" : {string},
 "signature_algorithm" : {string},
 "sign_identity_id" : {string}
}


PropertyDescription
digest_value
Hash of the data to be signed encoded in base64.
signature_algorithm
Algorithm that must be used to generate the digital signature ("rsa-sha1", "rsa-sha256", "rsa-sha384" and "rsa-sha512")
sign_identity_id
Identifier of the signing identity that must be used for generating the signature (it must be a server signing identity that belongs to the end-user on behalf of whom the signature is performed).

Example

POST /trustedx-resources/esigp/v1/signatures/server/raw
Host: eidas.eparaksts.lv
Content-Type: application/json
Authorization: Bearer cbc...6daf
Content-Length: 213
{
   "digest_value" : "n4bQgYhMfWWaL+qgxVrQFaO/TxsrC4Is0V1sFbDwCgg",
   "signature_algorithm" : "rsa-sha256",
   "sign_identity_id" : "nio...omq"
}

Response

Response contains the binary value of the PKCS #1 signature.

If you are using Sign API service, PKCS#1 shall be base64 encoded (hexToBase64)



Elektroniskā paraksta paketes izveidošana serverī

Description

Creates a batch of digital signatures from the hashes of the data to be signed using a server signing identity. 

The signature is created with the signing identity on server specified in the request. This identity must belong to the end-user on behalf of whom the operation is performed.

This method can be used for single signing as well. Main differences: Batch method response with base64 encoded Signed data, but single signing method response with PKCS#1 raw signature.

Request

POST /trustedx-resources/esigp/v1/signatures/server/raw/batch

Content-Type Header

Content-Type: application/json

Body

{
    "sign_identity_id" : {string},
    "signature_algorithm" : {string},
    "requests" : [
        {
            "digest_value" : {string},
			"signature_algorithm" : {string}
        }
    ]
}


PropertyDescription
sign_identity_id
Identifier of the signing identity that must be used for generating the signature (it must be a server signing identity that belongs to the end-user on behalf of whom the signature is performed).
signature_algorithm
Algorithm for obtaining the cryptographic hashes to be used for generating the signatures (rsa-sha1rsa-sha256rsa-sha384 and rsa-sha512) if no other algorithm is specified for each of them.
requests[ ]
Information on the cryptographic hashes to be used for generating the signatures.
requests[ ].digest_value
Base64 encoding of the cryptographic hash used to generate the signatures.
requests[ ].signature_algorithm
Algorithm that must be used to generate one of the digital signatures ("rsa-sha1", "rsa-sha256", "rsa-sha384" and "rsa-sha512").

Access Control

The request must contain a bearer access token generated by a trusted authorization server associated to the domain of the signing identity to be used for generating the signature. This token must have a scope that includes the value configured for the signing identity (by default, urn:safelayer:eidas:sign:identity:use:server) and must be used as explained in RFC 6750. Basically, the token must be included in an Authorization header as follows:

Authorization: Bearer <token>

The access token must be obtained via an authorization code grant OAuth 2.0 flow.

Example

POST /trustedx-resources/esigp/v1/signatures/server/raw/batch
Host: eidas.eparaksts.lv
Content-Type: application/json
Authorization: Bearer cbc...6daf
Content-Length: 213
{
	"sign_identity_id": "12345678",
    "signature_algorithm": "rsa-sha1",
	"requests": [
        {
            "digest_value": "RXN0byBlcyB1biBoYXNoIFNoYTE=",
            "signature_algorithm": "rsa-sha1"
       	},
       	{
            "digest_value": "siHZ27CDp/M0KNfCo8MZiuklYU1wIQ4ocWzKp81N23k",
            "signature_algorithm": "rsa-sha256"
        }
    ]
}

Response

Body

{
    "signatures" : [ {string} ]
}
PropertyDescription
signatures[]

Digital signatures encoded in base64. The signatures follow the same order as the cryptographic hashes from which they were created appear in the request.


Identitātes pakalpojuma sniedzēja API

User Session And Its Termination

Description

When the end-user is successfully authenticated, the identity provider maintains authenticated end-user session, which is to be used for repeated request. Identity provider support end-user authentication from different information systems, where end-user already has authenticated.

Identity provider maintained session usually is not necessary to terminate, it can affect end-user experience with single sign-on functionality.

In situations where there is a need to stop the identity provider authenticated end-user's session, then it is necessary to perform the following HTTP GET request.

The session may be terminated at the time when the information about the end-user is obtained. It is necessary to take into account if Integration platform document signature functionality is used then the session must be stopped as required.

Request

GET /trustedx-authserver/{idp}/logout?redirect_uri=...

Parameters - take into account the fact that all parameters are converted using the UTF- 8 character encoding URL encoding and conditions.

Title

Type

Used

Description

idp

path

mandatory

Identity provider and its identifier available to the Service provider’s application.

redirect_uri

query

mandatory

Service provider’s application web address where to redirect the end-user.

Example

The following example shows a situation where end-user's session is terminated by identity provider "lvrtc-eips-idp".

GET /trustedx-authserver/lvrtc-eips-idp/logout?redirect_uri=https%3A%2F
%2Fwww.demoapp.lv HTTP/1.1
Host: eidas.eparaksts.lv


UML datu plūsmas diagrammas autentifikācija un parakstīšana

Lietošana (Identifikācija un parakstīšana)

This use case contains full flow starting with end-user identification till receiving PKCS#1 signature in logical sequence.

If there is a need to only identify end-user, use only "Electronic identification of end-user".

All subchapter names are created from paragraph names in which you can find detailed explanation of the specific operation.


Obtain Authorization code

Request 

 urn:lvrtc:fpeil:aa scope shall be used 


GET /trustedx-authserver/oauth/{as}?response_type=code&
   client_id=...&
   state=...&
   redirect_uri=...&
   scope=...&
   prompt=...&
   acr_values=...&
   ui_locales=...&

Response

GET {redirection_uri_path}?code={code}&state={state}
HTTP/1.1
Host: {redirection_uri_host}

Obtain a access token

Request example

Using "code" value received from previous operation


POST /trustedx-authserver/oauth/lvrtc-eips-as/token HTTP/1.1
Host: eidas.eparaksts.lv
Authorization: Basic cG9ydCVDNCU4MWxzOmRybyVDNSVBMSVDNCVBQmJh
Content-Type: application/x-www-form-urlencoded;
charset=UTF-8
grant_type=authorization_code&
     redirect_uri=https://www.demoapp.lv/oauth/back&
     code=4515...e0ban

Response example

{
"access_token" : {string},
"token_type" : "Bearer",
"expires_in" : {number}
}

Obtain Information About the Authenticated User

Request example

Using Access token received from previous operation


GET /trustedx-resources/openid/v1/users/me
Host: eidas.eparaksts.lv
Authorization: Bearer a2b4...6daf

Response example for urn:lvrtc:fpeil:aa scope

HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8
Date: Thu, 16 Nov 2017 10:14:21 GMT
{
"sub": "ddf12735f35675ecb652e6e1a80e41f1",
"domain": "citizen",
"acr": "urn:safelayer:tws:policies:authentication:level:high",
"amr":["urn:eparaksts:tws:policies:authentication:adaptive:methods:sc_plugin"],
"given_name": "ANDRIS",
"family_name": "PARAUDZIŠ",
"name": "ANDRIS PARAUDZIŠ",
"serial_number": "PNOLV-010180-15097",
"eips": "VAS \"Latvijas Valsts radio un televzijas centrs\""
}

Obtain Authorization code

Request 

urn:safelayer:eidas:sign:identity:profile scope shall be used


GET /trustedx-authserver/oauth/{as}?response_type=code&
   client_id=...&
   state=...&
   redirect_uri=...&
   scope=...&
   prompt=...&
   acr_values=...&
   ui_locales=...&

Response

GET {redirection_uri_path}?code={code}&state={state}
HTTP/1.1
Host: {redirection_uri_host}

Obtain a access token

Request 

Using "code" value received from previous operation 

POST /trustedx-authserver/oauth/lvrtc-eips-as/token HTTP/1.1
Host: eidas.eparaksts.lv
Authorization: Basic cG9ydCVDNCU4MWxzOmRybyVDNSVBMSVDNCVBQmJh
Content-Type: application/x-www-form-urlencoded;
charset=UTF-8
grant_type=authorization_code&
     redirect_uri=https://www.demoapp.lv/oauth/back&
     code=4515...e0ban

Response

{
"access_token" : {string},
"token_type" : "Bearer",
"expires_in" : {number}
}

Obtain Information About the Authenticated User (Getting signing identities)

Request

Using Access token received from previous operation

GET /trustedx-resources/openid/v1/users/me
Host: eidas.eparaksts.lv
Authorization: Bearer a2b4...6daf

Response example for urn:safelayer:eidas:sign:identity:profile scope

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{"sign_identities": [
        {"id": "a46...hu6",
            "status": {
                "value": "enabled"
            },
            "labels": [
                "serverid",
                "x509:keyUsage:contentCommitment",
                "eparaksts",
                "serveridVersion1"
            ],
            "domain": "citizen",
            "links": {
                "Signatures.create.server.raw": {
                    "auth": {
                        "oauth2": {
                            "scopes": [
                                "urn:safelayer:eidas:sign:identity:use:server"
                            ]
                        }
                    }
                }
            },
            "self": "https://eidas-demo.eparaksts.lv/trustedx-resources/esigp/v1/sign_identities/a46...hu6",
            "access": [
                {"user_id": "55f...16d"
                }
            ],
            "type": "pki:x509"
        },
        {"id": "oth...516",
            "status": {
                "value": "enabled"
            },
            "labels": [
                "mobileidVersion1",
                "eparaksts",
                "mobileid",
                "x509:keyUsage:digitalSignature"
            ],
            "domain": "citizen",
            "device_id": "ae34dd7.........104a2",
            "self": "https://eidas-demo.eparaksts.lv/trustedx-resources/esigp/v1/sign_identities/oth...516",
            "access": [
                {
                    "user_id": "55f...16d"
                }
            ],
            "type": "pki:x509"
        }
    }

Obtain Signing Identity Information (Getting Signing or Authentication certificate)

Request

Authentication certificate

To receive authentication certificate, you shall read and use  id value (from previous operation) where labels array contains mobileid tag.

Authentication certificate is needed if you are using Sign API service for finalizing signature.

Signing certificate

To receive signing certificate, you shall read and use id value (from previous operation) where labels array contains serverid tag.

Signing certificate is needed if you are using Sign API service or other solution to sign signable data according to XAdES or PAdES specification.

You also need to make sure the status value is enabled. 

GET /trustedx-resources/esigp/v1/sign_identities/a46...hu6
HTTP/1.1
Authorization: Bearer mF_9.B5f-4.1JqM

Response

{
 "id" : {string},
 "self" : {string},
 "description" : {string},
 "labels" : [ {string} ],
 "type" : {string},
 "device_id" : {string},
 "domain" : {string},
 "access" : [ {
 "user_id" : {string}
} ]
"details" : {
     "certificate" : {string},
"activation_mode": {string},
"public_key" : {string}
},
"links" : {
   <operation_alias> : {
     "auth" : {
"oauth2": {
    "scopes": [ {string}
]
 }
 }
 }
},
  "status" : {
  "value" : {string},
  "reason" : {string}
 }
}

details.certificate property contains X.509 certificate encoded in DER and base64.

Authentication certificate is used in Sign API service for finalizing certificate.

Signing certificate is used to calculate signable data.

Obtain Authorization code

Request

urn:safelayer:eidas:sign:identity:use:server scope shall be used

GET /trustedx-authserver/oauth/{as}?response_type=code&
   client_id=...&
   state=...&
   redirect_uri=...&
   scope=...&
   prompt=...&
   acr_values=...&
   ui_locales=...&
   sign_identity_id = ...&
   digests_summary = ...&
   digests_summary_algorithm = ...&

sign_identity_id value is previously received value

digests_summary value ir signable data calculated by using received signing certificate

At this point end-user with active SSO session enters HSM password in redirected page

Response

GET {redirection_uri_path}?code={code}&state={state}
HTTP/1.1
Host: {redirection_uri_host}

Obtain a access token

Request

Using "code" value received from previous operation


POST /trustedx-authserver/oauth/lvrtc-eips-as/token HTTP/1.1
Host: eidas.eparaksts.lv
Authorization: Basic cG9ydCVDNCU4MWxzOmRybyVDNSVBMSVDNCVBQmJh
Content-Type: application/x-www-form-urlencoded;
charset=UTF-8
grant_type=authorization_code&
     redirect_uri=https://www.demoapp.lv/oauth/back&
     code=4515...e0ban

Response

{
"access_token" : {string},
"token_type" : "Bearer",
"expires_in" : {number}
}

Create a Digital Signature on the Server

Request

Using "sign_identity_id" value received from previous operations and "digest_value" value calculated by using received signing certificate.

If you are using Sign API service, then received "diggest" property value from the calculateDigest operation response shall be used as "digest_value" value

POST /trustedx-resources/esigp/v1/signatures/server/raw
Host: eidas.eparaksts.lv
Content-Type: application/json
Authorization: Bearer cbc...6daf
Content-Length: 213
{
"digest_value" :
"n4bQgYhMfWWaL+qgxVrQFaO/TxsrC4Is0V1sFbDwCgg",
"signature_algorithm" : "rsa-sha256",
"sign_identity_id" : "nio...omq"
}

Response

Response contains the binary value of the PKCS #1 signature.




  • No labels