...

...

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 above to quickly navigate to the section of interest. 

Document versions

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:

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

All JWS headers are, therefore, identical and equal to the following:

eyJhbGciOiJSUzI1NiIsIng1dCI6InNIODBvb0F1Rzg5a1MxM2xfUl9Pdk1MM1daQSJ9

Identity assertion service

Freja eID Identity assertion service is used by entities that wish to perform identity switching, or simply wish to receive confirmation of strong authentication for an individual. The following diagram illustrates the flow of control for this service.

Image Removed

In step one, the relying party invokes a custom URL on a device where Freja eID mobile app is installed. The URL passes RP identity, protocol version and opaque data as parameters. In step two, Freja eID mobile app sends these parameters to the back end for validation - if something is wrong, an error is immediately displayed in the Freja eID app.

As far as Step 3 is concerned, it is worth noting that a prerequisite for the identity assertion service is that the user has been vetted to Freja eID+. In order to make the identity assertion service as user-friendly as possible, the process can be initiated (Step 1 in the diagram above), regardless of whether the user is at Freja eID Basic or Freja eID+ level. However, the completion is only possible once the user has vetted their identity to Freja eID+. Thereby, the following two scenarios can occur:

• The identity assertion service is initiated through either of the methods above and the user has Freja eID Basic. A transaction is queued in the Freja eID server side, but cannot be approved by the end user until the user raises the assurance of their identity to Freja eID+.
• The identity assertion service is initiated through either of the methods above and the user already has Freja eID+. The transaction can immediately be displayed for the user. Following the user's approval through either a PIN or biometric method (for example, TouchID), the transaction is completed on the server side.

Once the user's approval is received and processed, Step 3 can commence and a response is sent back to the relying party that requested identity assertion. The posted data will contain the country and SSN of the individual associated with the Freja eID app residing on the mobile device where the process of identity assertion was initiated.

Before you begin

There are several technical requirements that must be in place before the implementation can start. Please complete the checklist below before proceeding:

• Obtain a symmetric key and a Relying party ID from Verisec for accessing the test environment. The RP ID is a unique identifier of the organisation which uses Freja eID.
• Obtain the JSON Web Signature (JWS) certificate of Freja eID test environment and import it into your system. 
• Provide Freja eID with an HTTPS endpoint for receiving identity assertions in your test environment (e.g. https://relyingparty.com:8443/identityAssertionServer) and your endpoint certificate chain.

Production checklist

• Sign a contract providing your organisation access to the Identity assertion service
• Obtain a symmetric key and a Relying party ID from Verisec for accessing the production environment. The RP ID is a unique identifier of the organisation which uses Freja eID.
• Obtain the JSON Web Signature (JWS) certificate of Freja eID and import it into your system. 
• Provide Freja eID with an HTTPS endpoint for receiving identity assertions (e.g. https://relyingparty.com:8443/identityAssertionServer) and your endpoint certificate chain.

Identify method

This method is used for obtaining an assertion of end user's identity from the Freja eID service. A user must be vetted to level 3 (Freja eID+) before steps two and three in the diagram can be completed. In other words, while a relying party can invoke the Identify method regardless of the identity assertion level of the end user, the end user must be vetted to level 3 before they will be allowed to confirm releasing information about their identity to the relying party. It is, therefore, worthwhile pointing out that the flow above is not synchronous - step 1 can precede steps 2 and 3 by an arbitrary amount of time (controlled by the relying party, see the details of the method parameters below), giving an opportunity to the end user to complete the extended registration process. During this period, the user will be aware of a pending identity assertion action, but will not be able to complete it.

The method can be invoked from a browser or an application on the mobile phone on which the Freja eID app is installed. The invocation is actually performed through opening a custom URL with a scheme registered by the Freja eID app. Preconditions for a successful operation are, therefore, that the Freja eID is installed on the device before the custom URL is invoked, and that the mobile device is online as the Freja eID must contact the Freja eID infrastructure in order to fulfil the request. The custom URL should be constructed as follows:

frejaeid://identify?iaRequestData=abcdefgh

where the content of the iaRequestData parameter is described in the table below.

{
  "kid": "key id",
  "alg": "algorithm used to secure the JWS"
}

{ 
   "iarp":"Identity assertion relying party reference",
   "exp":"Expiry time for the request",
   "proto":"The response protocol",
   "opaque":"Relying party correlation data"
}

Example request:

eyJraWQiOiJSUE5BTUVfS0lEIiwiYWxnIjoiSFMyNTYifQ.eyJleHAiOjE0OTM4MDY1MzAwMDAs
Im9wYXF1ZSI6IkFCQ0RFRkdISUpLTE1OT1BSU1RVVldYWVowMTIzNDU2Nzg5MDEyMzQiLCJwcm9
0byI6IjEuMCIsImlhcnAiOiJSUE5BTUUifQ.ys4o7XQE4v43pKjbtFowg9o9TDQAAKXR39uBssF
Grfo

Possible errors when initiating the request

The error codes that may be displayed by the Freja eID mobile application upon initiating an identity assertion request have the following meanings:

Posting the identity data

The relying party is responsible for operating a web service where Freja eID will post responses containing the requested identity information once the end user approves that. The exact URL is determined between the relying party and Freja eID upon onboarding the relying party to the service (see 3.0 Draft Freja eID Relying Party Developers' Documentation above). A response to the relying party is only posted once a user confirms the release of their social security number to the relying party that initiated the request. Please observe that no response will ever be posted if:

• the request initiated through the customer URL above was invalid, resulting in an error displayed within the Freja eID app;
• the user has not completed the extended registration process to vet their identity to level 3 before, or within the stipulated time limit, provided by the relying party when the request was initiated;
• the user has ignored confirming the action or has actively cancelled the release of their SSN to the initiating relying party.

It is the responsibility of the relying party to clean up any outstanding data and transactions on its end, pertaining to initiated identity assertion requests which have not been responded to within the time limits of the "exp" parameter (see the parameters above).

https://<determined by relying party>/verisec/vetting-result

The call is made using the HTTP POST method with the following JSON structure in the body:

{
  "x5t": "SHA-1 digest of the signing certificate",
  "alg": "algorithm used to secure the JWS"
}

{
"ref":"transaction reference",
"opaque":"Opaque data as submitted in request",
"country":"Country related to social security number"
"ssn":"Social security number"
}

Example data:

eyJyZWYiOiIxMjM0LjU2NzguOTAxMi4zNDU2Iiwib3BhcXVlIjoiQUJDREVGR0hJSktMTU5PUFJ
TVFVWV1hZWjAxMjM0NTY3ODkwMTIzNCIsInNzbiI6IjE5OTAxMDEwMTAxMCIsImNvdW50cnkiOi
JTRSJ9.u1V8x-yxGtU10zIvWF_RK6l_Tfrk3zWajhuvMICGDnWN3hYZCzfSGHG3oerrbMIXPhET
48BEufWFJE0zQbWxBGXLAru9lvWsQoaYPBJJAuVZMj-ZV1-PhUgtONrVfGuSJR6cVRj42IxyUtw
ZEecbw37Dnip3KDkllZ5_WOSZEhJsC8lxyIYfAF7lD9q2Ln4wgZiTRJSe8KGJiat4c7jd__RlHu
AE7GPZ7aQcN_nqdBWrDK8SufvESQJQxW8LrAAwb0bWvT5R3hOSAMMx6BWhCZewnb7UYabSuZO06
6tDGOMbjTqGBaM9MmuRzVU452mOr1EGrkbHKlltqUw3gYFpOQ 

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.

{
   "code": "Integer with error code value",
   "message": "Error description"
} 

Authentication services

...

Image Removed

In step one, a relying party invokes the Freja eID authentication service submitting a user identifier and, optionally, a Freja eID assurance qualifier (Freja eID or Freja eID+), and requests that the user approves authentication to a service operated by the relying party. Should the relying party service be residing on the same mobile device (i.e. accessed through a mobile browser or mobile app), the service can activate the Freja eID mobile application directly. Otherwise, the service will need to instruct the end user to start the Freja eID mobile application on one of the enabled devices. In step two, the Freja eID mobile application and authentication service work on presenting the login request to the end user and solicit approval for it. Finally, in step three, the relying party polls for the status of the authentication request until it receives a positive result or an error allowing it to proceed with allow, or reject end user access to its service, respectively.

Before you begin

There are several technical requirements that must be in place before the implementation can start. Please complete the checklist below before proceeding:

• Obtain an SSL client certificate providing you access to the Freja eID test environment.
• Import Freja eID Test root certificate as trusted into the trust store of your application.
• Using Freja eID mobile application, register one or more users with the Freja eID Test infrastructure.

Production checklist

In order to use Freja eID in a production environment, you must fulfil the following:

• Sign a contract allowing your organisation to access the production Freja eID Authentication service.
• Provide Freja eID with a logo suitable to represent your organisation in the mobile application, as well as a display name. The logo must be delivered in one of the vector file formats: .ai, .eps or editable .pdf.
• Obtain an SSL client certificate providing you access to the Freja eID production environment.
• Import Freja eID Production root certificate as trusted into the trust store of your application.

Initiate authentication method

This method is used by a relying party to initiate an authentication request. The method is intended for authentication in online contexts where the access to the relying party's service or application is initiated by the end user. The authentications are therefore short-lived — from the point of initiation, the user has a maximum of two minutes to confirm the authentication through a Freja eID mobile application. Only one active authentication may exist for any given end user at any given time. An attempt to concurrently start a second authentication, by the same or a different relying party, will cancel both initiated authentication requests.

The method is called using HTTP POST through the URLs below:

https://services.test.frejaeid.com/authentication/1.0/initAuthentication

https://services.prod.frejaeid.com/authentication/1.0/initAuthentication

The parameter of the method is a Base64 encoded JSON payload according to the following:

{
   "userInfoType":"User info type",
   "userInfo":"User information corresponding to user info type",
   "askForBasicUserInfo": true,
   "restrict":"Restricts the login request to a specific mobile device",
   "minRegistrationLevel":"Minimum required registration level of a user"
}

{
"country":"Country of SSN",
"ssn":"Social security number of the end user"
}

Possible errors returned by the method are the following:

If HTTP 200 is returned from the method, the following return value will be present in the body of the response:

{ 
   "authRef":"Reference to be submitted in getAuthResults method"
}

Initiating Freja eID app in authentication mode

The method can be invoked from a browser or an application on the mobile phone on which the Freja eID app is installed. The invocation is actually performed through opening a custom URL with a scheme registered by the Freja eID app. Preconditions for a successful operation are, therefore, that the Freja eID is installed on the device the custom URL is invoked, and that the mobile device is online, as the Freja eID must contact the Freja eID infrastructure in order to fulfil the request. The custom URL should be constructed as follows:

frejaeid://authenticate?restrict=abcdefgh

Methods for retrieving authentication results

There are two methods that can be used for fetching authentication results: one that returns a single result for a specified authentication reference (authRef returned from a call to 3.0 Draft Freja eID Relying Party Developers' Documentation), and one that returns multiple authentication results. The latter is the preferred way of fetching results in situations where a relying party has many concurrent authentications in progress, as it reduces the number of polling requests.

Get one authentication result method

The method is called using HTTP POST through the URLs below:

https://services.test.frejaeid.com/authentication/1.0/getOneResult

https://services.prod.frejaeid.com/authentication/1.0/getOneResult

The parameter of the method is a Base64 encoded JSON payload according to the following:

{
   "authRef":"Authentication reference"
}

Possible errors returned by the method are the following:

If HTTP 200 is returned from the method, the following return value will be present in the body of the response:

...

...

{
   "authRef":"Authentication reference",
   "status":"Authentication status",
   "basicUserInfo":{"name":"user's name","surname":"user's surname"},
   "details":"JWS signed data, see below"
}

authRef: string, mandatory. The authentication reference of the authentication.
status: string, mandatory. One of: STARTED (the transaction has been started but not yet delivered to Freja eID application associated with the end user), DELIVERED_TO_MOBILE (the Freja eID app has downloaded the transaction), CANCELLED (the end user declined the authentication request), EXPIRED (the authentication request was not approved by the end user within the authentication validity limit of two minutes), APPROVED (the authentication was successful) or REJECTED (e.g. if you try to run more than one authentication transaction for the same user at the same time).
basicUserInfo: JSON object (see below), optional. Provides additional attributes about user if the askForBasicUserInfo in related initAuthRequest was set to true and status is APPROVED. 
details: JWS signed object (see below), optional. Provides details and evidence of the authentication if status was equal to APPROVED.

...

...

Signature services

Freja eID Signature services allow relying parties to securely deliver messages to a user, as well as to prompt Freja eID end users to digitally sign data and documents. The end user will have previously downloaded the Freja eID mobile application on one or more iOS or Android devices they possess, and registered with Freja eID, allowing them to be referred to by relying parties through the use of one or more email addresses. Signature services are available to both Basic and end users that have upgraded to Freja eID+. Signatures created by the end users are PKI-based and therefore non-repudiable.

The signature flow is practically identical to that of authentication depicted in the section on 3.0 Draft Freja eID Relying Party Developers' Documentation. The key difference is that whereas a user can only have one authentication transaction active at any given time and the duration of authentication transactions is limited to two minutes, multiple signatures can be pending for a user's approval and each individual signature transaction can be open for up to 30 days (i.e. from the initiation by a relying party an end user may have up to 30 days to perform the signing). This allows for flexible signing solutions to be built on top of Freja eID where users can be prompted to sign even outside a direct online context.

Signature types

Freja eID allows for several types of signatures.

Simple signature type

The SIMPLE signature type allows signing of UTF-8 text. Upon completion of the signature by the user, the relying party receives a JWS structure containing the data that was presented to the user, as well as evidence that the Freja eID infrastructure has validated the signature.

Extended signature type

The extended signature type allows signing of UTF-8 text (presented to the user) alongside binary data (not presented to the user). Upon completion of the signature by the user, the relying party receives a JWS structure containing the data that was presented to the user and the supplied binary data, as well as evidence that the Freja eID infrastructure has validated the signature.

Advanced signature type

The advanced signature type allows signing of UTF-8 text (presented to the user), binary data (not presented to the user) or both to be signed in XML or CMS formats. Subject to the type of binary data, the value returned to the relying party will be one of the following:

{
   "authRef":"Authentication reference",
   "status":"Authentication status",
   "userInfoType":"User info type",
   "userInfo":"User information corresponding to user info type",
   "basicUserInfo":{"name":"user's name","surname":"user's surname"},
   "timestamp":"Time when authentication confirmed by end user"
}

{
"authRef":"12345-67890-abcdef",
"status":"APPROVED",
"details":"JWS content as per below",
"basicUserInfo": {
                   "name":"John",
                   "surname":"Doe"
                 }
}

eyJ1c2VySW5mbyI6ImpvaG4uZG9lQHNvbWVkb21haW4uY29tIiwidXNlckluZm9UeXBlIjoiRU
1BSUwiLCJiYXNpY1VzZXJJbmZvIjp7InN1cm5hbWUiOiJEb2UiLCJuYW1lIjoiSm9obiJ9LCJh
dXRoUmVmIjoiMTIzNDUtNjc4OTAtYWJjZGVmIiwic3RhdHVzIjoiQVBQUk9WRUQiLCJ0aW1lc3
RhbXAiOjE0OTEzODgxNjMzODl9.p7jFO0m3iZF84edbZtzvy5qLWnsNAVzZZ2QoW9FnZ3qSvS3
iWEAFoIfqyQHNbNHfjavQ90224k89DMHoe2IPEnDR7TiDzOEna8GTM9rRcRZcARrNYclzqMtgl
J3hdxK0yyrk2P553wQJLqrYTft3DlJKVAuxmpCh3fcr-FfN5qiHrK7gCm60660zFJFV76AwTbt
4mlanlOLVUE5rvE4Yb2Fh7u6Ls3HVz1zOyFW0geA-cJjL0PhUeXpHKaiRFBYog_oO0uYf9V37j
QhzlV_FfDIVWSwm6jw-ZqwF__HSx2LpT4sVp0f5XfRZZCvR3Gj3AauaXLmrv7rWR1VO1WC7Uw

https://services.test.frejaeid.com/authentication/1.0/getResults

https://services.prod.frejaeid.com/authentication/1.0/getResults

{
   "includePrevious":"Include previously returned results"
}

{
"authenticationResults":[
    {
      "authref":"Authentication reference",
      "status":"Authentication status",
      "details":"JWS signed data, see below",
      "basicUserInfo":{
                        "name":"John",
                        "surname":"Doe"
                      }
    },
    {
      "authref":...
    }
  ]
}