User information provider API

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

End-user Data Scopes

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:

AttributeDescription
serial_numberPersonal code format PNOLV-XXXXXX-XXXXX
nameFirst name and last name
given_nameFirst name
family_nameLast name
EipsElectronic identification service provisioning data

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

AttributeDescription
urn:lvrtc:fpeil:aaBase data contains the following attributes:

given_name
family_name
name
serial_number
eips
urn:safelayer:eidas:sign:identity:profileObtaining of the information on the end-user's electronic signing identities.

This scope allows obtaining the sign_identities claim.

Obtain Information About the Authenticated User

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:

PropertyDescription
subIdentifier of the end-user (the value of the id attribute obtained by the authentication flow applied).
domainIdentifier of the domain in which the end-user was authenticated.
acrAuthentication 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.
amrThe 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:

PropertyDescription
{attribute1}
{attribute2}
...
Identifier of the end-user (the value of the id attribute obtained by the authentication flow applied).
sign_identitiesInformation 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