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:
Attribute | Description |
---|---|
serial_number | Personal code format PNOLV-XXXXXX-XXXXX |
name | First name and last name |
given_name | First name |
family_name | Last name |
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. |
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:
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
Updated almost 2 years ago