Thank you for subscribing to Freja eID services.
Freja eID is an electronic identification (eID) solution for citizens and organisations which can be used for identity assertion, authentication and signing. The essential part of Freja eID service is a smartphone application used for login and signing to all the services that are connected to the user´s eID. The second part is a web portal – My Pages – where the user can control how their eID is to be used and has a full record of user history.
In terms of relying parties, Freja eID offers great flexibility in terms of addressing end users. For example, the identity assurance level of end users registered with Freja eID can vary. If the user has followed an entry-level registration flow, their identity will be assured to level 2 within the scheme, also known as Freja eID Basic. At this level a user will have confirmed an email address and/or a mobile phone number, perfectly enough to allow, for example, login authentication in situations where an absolute identity is not of significance for the relying party - knowing that the end user accessing a relying party's service is the same one that accessed the service a week ago without the hassle of teaching the end user an additional password is perfectly enough for many web-based services.
However, if the end user opted for an extended registration process, their identity will be assured to level 3 within the scheme, also known as Freja eID+. The extended registration process involves, amongst other controls, vetting physical ID documents of the end user and face enrolment with Freja eID. Freja eID+ users can be referred to through their social security number (SSN). In Sweden, this would equate to having established a "personnummer" for the end user. Also, Freja eID+ users can be involved in interactions with web parties that involve login, but also legally binding signatures and identity assertion. If you want to find out more about identity assertion levels, please have a look at the Tillitsnivåer för elektronisk legitimation published by the Swedish e-Identification board.
This document contains instructions for enabling relying party (RP) applications to use services offered by Freja eID. It is of a technical nature - if you are not a software architect or developer, it is probably the wrong document to read.
Freja eID offers three services to RPs: Identity assertion service, Authentication service and Signing service. Our recommendation is to read the sections of interest to you in their entirety at least once. On later occasions, use the links to quickly navigate to the section of interest.
Document versions
| Version | Date | Comment |
|---|---|---|
| 1.0 | 2017-04-26 | This document is a preliminary version. The content of this document is still under review and subject to change. |
| 2.0 | 2017-05-29 | Included Authentication services. Changed examples to use signing certificate under Freja eID TEST root. |
| 2.1 | 2017-06-23 | Adjusted error codes to comply with conventions within other services. |
| 2.2 | 2017-06-30 | Adjusted error codes for validation errors. Instead of generic error 1000 and list of specific errors, specific error is returned directly. |
| 2.3 | 2017-08-03 | Opaque data must be max 128 characters long. Adjusted identity assertion error codes. |
| 2.4 | 2017-08-10 | Changed the URL for posting the response for identity assertion. |
| 2.5 | 2017-09-13 | Changed the JWS header value from x5c to x5t. |
| 2.6 | 2017-11-01 | Added support for requesting additional user attributes when initiating the authentication. |
| 3.0 | 2018-01-19 | Changed the endpoint URLs for all authentication service methods. Adjusted error codes in Authentication services. Included Signature services. |
Getting started
Certificates
There are several examples where the data has been signed using RSA keys and certificates below. In all cases, the private key corresponding to the following certificate chain has been used:
| Certificate | Details |
|---|---|
| End-entity (for signing key) | Subject: CN=Documentation and Demo, OU=Test, O=Verisec Freja eID AB, OID.2.5.4.97=559110-4806, L=Stockholm, C=SE
Base64 encoding: MIIEDTCCAvWgAwIBAgIUaKpKqy2TcGQeNQfUIZZD9jEzk5MwDQYJKoZIhvcNAQELBQAwgYMxCzA JBgNVBAYTAlNFMRIwEAYDVQQHEwlTdG9ja2hvbG0xFDASBgNVBGETCzU1OTExMC00ODA2MR0wGw YDVQQKExRWZXJpc2VjIEZyZWphIGVJRCBBQjENMAsGA1UECxMEVGVzdDEcMBoGA1UEAxMTUlNBI FRFU1QgSXNzdWluZyBDQTAeFw0xNzA1MTcyMTE5MjNaFw0yMDA1MTcyMTE5MjNaMIGGMQswCQYD VQQGEwJTRTESMBAGA1UEBxMJU3RvY2tob2xtMRQwEgYDVQRhEws1NTkxMTAtNDgwNjEdMBsGA1U EChMUVmVyaXNlYyBGcmVqYSBlSUQgQUIxDTALBgNVBAsTBFRlc3QxHzAdBgNVBAMTFkRvY3VtZW 50YXRpb24gYW5kIERlbW8wggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQDBwTeuSLvrd Ot8PJ3dfnlDS+tyTV5P35sm/UusrasPya0XUV3ctj8RxD2skLHYMZ10X87EvXBUw4FEKJ9YlwTO A3UjZ3jXYX9TZlU/r0kZsvf4RBZO8MOje00oRRdx0go4L6SsTcoBQhgimkxBMcCY1aHqGDWMH61 DWxbepa/4Df6xuFegnMQp421mR2FFvRUi74HBCn35oVHZhYviWo7aTyPVFWd2wLN8GiV+jwunHU Tdq61+f9pqhPJ0CM6VL9oAIl0D0LbDHbMUd4XuV1hB9wM5jKZaGQ3388rWs+9a83/BJjb1Wa5qD 9tICuIl8y/asOcQEuvX7fT7xyPwduvLAgMBAAGjdDByMA4GA1UdDwEB/wQEAwIGwDAMBgNVHRMB Af8EAjAAMB8GA1UdIwQYMBaAFGp8ig+dcA4c2l8toDwmX4joFb+cMBIGA1UdIAQLMAkwBwYFKgM EBQowHQYDVR0OBBYEFHgMFxByq68FGuntjoOa+TTXw/7/MA0GCSqGSIb3DQEBCwUAA4IBAQCV9g 0ZuHBWOIdqiLDss/kTr0Obaeap4DEF5uuuxqo2LKn0k1qGHh66uLdxS0i1nWyLZjphPi5l8CxxM uhw0VZ90u4cguTYsUXy/s1dp12e48m7bVOz/SnghU8ag+2pAO1esSn3LJ0nOMlKe32IMuGLUXPR ELG151DEam/3yWKeCtEkthPisDLUKHKoc9v6EQEo+IVkGluSWPaIpvdbJpISzW3c0m9Qzu+GqWj A1ac/BzdHql0UyTIoXB6u2VVbuIAkTLVLeFWlnL6dOD4XoChN9LStqYKn4iovO+DA+AtQt8Q+4B /8hQnMyNby0Zyn5BJw4dqDWCju5PIFct8IvYuu |
| Intermediate | Subject: CN=RSA TEST Issuing CA, OU=Test, O=Verisec Freja eID AB, OID.2.5.4.97=559 110-4806, L=Stockholm, C=SE |
| Root | Subject: CN=RSA Test Root CA, OU=Freja eID, O=Verisec AB, C=SE |
All JWS headers are, therefore, identical and equal to the following:
| Field | Value |
|---|---|
| Header | "alg":"RS256" |
Base64 encoding of header | eyJhbGciOiJSUzI1NiIsIng1dCI6InNIODBvb0F1Rzg5a1MxM2xfUl9Pdk1MM1daQSJ9 |
General information about Freja eID RESTful APIs
Authentication and Signing services are exposed through a RESTful API. This section presents information common to both services. Firstly, the following applies to HTTP response codes.
HTTP response code | Interpretation |
|---|---|
| 200 OK | Success, additional information is available in the body. |
| 204 No Content | Success, no additional information is available in the body. |
| 400 Bad Request | The request is malformed. For example, the body cannot be parsed. |
| 404 Not Found | Requested resource does not exist. |
| 410 Gone | Requested resource is no longer available. For example, an obsolete API version. |
| 422 Unprocessable Entity | Validation or processing errors. Additional information is available in the body. If the input is corrected, the request can be resubmitted. |
| 500 Internal server error | The request, although probably OK, could not be processed due to an internal server error. Repeating the request is not recommended, the application should return a sensible error message to the end user. |
General information on error handling
Where errors need to be conveyed (for example, in the case of HTTP 422 code for a RESTful API), the following structure is returned in the body. Note that the code and error message are always present in a case of error.
{
"code": "Integer with error code value",
"message": "Error description"
}