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:

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

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:

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

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