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” |
OAuth2.0 | User authentication and authorization standard |
PAdES | PDF advanced electronic signature/seal standard |
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
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.
Service provider's application password client_secret
is converted by using the UTF-8 character encoding and URL encoding conditions.
Both values of the previous two steps must be combined with separator colon “:” between them.
Obtained value must be converted using base 64 encoding without line breaks.
"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: Production: |
Client_ID | Service provider ID generated by LVRTC |
Client_secret | Service provider Access Password generated by LVRTC |
Scopes |
|
Authorization Endpoint | https://{Host}/trustedx-authserver/oauth/{as}? response_type=code& |
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} |
|
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 "
|
response_type | Query | Required | Must take the |
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:
|
prompt | Query | Recommended | The values login and none are supported:
|
acr_values | Query | Optional | Defines conditions for authenticating the end-user (minimum levels or specific flows) who must authorize the access. Defined authentication methods:
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:
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 |
Signing Identity received from authenticated end-user data request using |
digests_summary | Query | Optional |
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.
|
digests_summary_algorithm | Query | Optional |
Hash algorithm used to calculate |
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 " |
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 |
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 |
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 |
scope | mandatory | Must have the urn:safelayer:eidas:oauth:token:introspect value |
Introspect access token
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
Property | Description |
---|---|
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:
|
urn:safelayer:eidas:sign:identity:profile | Obtaining of the information on the end-user's electronic signing identities. This scope allows obtaining the |
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 |
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:
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:
This property is a JSON string array. |
Property | Description |
---|---|
{attribute1} {attribute2} ... | Identifier of the end-user (the value of the |
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
Name | Type | Usage | Description |
---|---|---|---|
sign_identity_id | path | Required | Identifier 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:
|
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.
|
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} }
Property | Description |
---|---|
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} } ] }
Property | Description |
---|---|
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-sha1, rsa-sha256, rsa-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} ] }
Property | Description |
---|---|
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 |
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.