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.

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.

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.

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.

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>))]

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 = ...&   

as

response_type

client_id

state

redirect_uri

scope

prompt

acr_values

ui_locales

sign_identity_id

digests_summary

digests_summary_algorithm

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.

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.

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

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)

grant_type

code

redirect_uri

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

grant_type

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.

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.

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.

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.

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 .
scope	mandatory	Must 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

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

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

access_token

token_type

expires_in

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
}

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:

given_name

family_name

name

serial_number

Eips

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

urn:lvrtc:fpeil:aa

urn:safelayer:eidas:sign:identity:profile

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:

sub

domain

acr

amr

{attribute1}

{attribute2}

...

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\""
}

{"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"
        }
    }

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

sign_identity_id

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}
 }
}

id

self

description

labels[ ]

type

device_id

domain

access[ ]

access[ ].user_id

details

details.certificate

details.activation_mode

details.public_key

links

links.<operation_alias>

links.<operation_alias>.auth

links.<operation_alias>.auth.oauth2

links.<operation_alias>.auth.oauth2.scopes[ ]

status

status.value

status.reason

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}
}

digest_value

signature_algorithm

sign_identity_id

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.

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.

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}
        }
    ]
}

sign_identity_id

signature_algorithm

requests[ ]

requests[ ].digest_value

requests[ ].signature_algorithm

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} ]
}

signatures[]