Table of contents

Other services

Management:

Overview

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.

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:

Custom URL scheme for invoking the Identify method
frejaeid://identify?iaRequestData=abcdefgh

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

 

Input Parameter Name
Value
iaRequestData

JWS in compact serialised form as following:

BASE64URL(UTF8(JWS Protected Header)) || ’.’ || BASE64URL(JWS Payload) || ’.’ || BASE64URL(JWS HMAC)

 

JWS Protected Header

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

kid: string, mandatory. The key id used to secure the message. The key (and its respective key id) are determined between Freja eID service and the identity assertion relying party when signing up for the service.
alg: mandatory, the value must be HS256.

 

JWS Payload

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

iarp: string, mandatory. Identity assertion relying party reference agreed at the time of enrolling the relying party for the service.
exp: long, mandatory. Describes the time until which the identity assertion relying party is ready to wait for the response. Expressed in milliseconds since January 1, 1970, 00:00 UTC. Min value is current time +5 minutes, max value is current time +60 days.
protocol: string, mandatory. Describes the protocol version to be used when posting the response. Currently, must be set to "1.0".
opaque: string, mandatory. A reference that Freja eID must return to the relying party upon a successful identity assertion completion. Note that Freja eID makes no attempt to interpret the opaque data. For a given relying party, the opaque data must be unique and non-repeatable. Should Freja eID receive a new request with opaque data identical to a current transaction, the pending request will be silently cancelled and overwritten by the latter one. Initiating a transaction with opaque data that Freja eID already considers completed will result in an error displayed within Freja eID app (see Possible errors when initiating the request below). Max value is 128 characters.

 

Example request:

Field
Value
Header

"alg":"HS256"
"kid":"RPNAME_KID"

Payload

"exp":1493806530000
"opaque":"ABCDEFGHIJKLMNOPRSTUVWXYZ012345678901234"
"proto":"1.0"
"iarp":"RPNAME"

Key value
(hexadecimal format)

000102030405060708090a0b0c0d0e0f000102030405060708090a0b0c0d0e0f

Final JWS (compact
format, line broken
for clarity only)
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:

Return code
Explanation
4000Decoding of JWS encoded iaRequestData failed. For example, it could not be separated into header, payload and signature parts.
4001Cannot perform JWS validation.Reason could be unsupported algorithm.
4002Validation of JWS digital signature failed. Reasons could include modifications of the JWS document after signing or a wrongly constructed signature.
4003Invalid signer. For example, unknown keyid.
4004Decoding of payload failed.
4005Invalid expiry time.
4006Unknown identity assertion relying party.
4007Unknown protocol.
4008Identity assertion relying party mismatch with specified keyid.
4009Relying party not subscribed to identity assertion.
4010Request already completed.
4011The user has disabled the relying party service.

 

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 Before you begin 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).

Posting the response
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:

Response parameter name
Value
iaResponseData

JWS in compact serialised form as following:

BASE64URL(UTF8(JWS Protected Header)) || ’.’ || BASE64URL(JWS Payload) || ’.’ || BASE64URL(JWS Signature)

 

JWS Protected Header

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

x5t: mandatory, Base64URL encoding of the certificate's SHA-1 digest.
alg: mandatory, value shall be RS256 which corresponds to 'RSA PKCS#1 signature with SHA-256'.

 

JWS Payload

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

ref: string, mandatory. Unique service transaction reference that can be used for further investigation related to the call.
opaque: string, mandatory. Opaque data as submitted in the original identity assertion request.
ssn: string, mandatory. Contains the social security number (SSN) associated with the vetted person whose identity is asserted through the response.
country: string, mandatory. Contains the ISO-3166 two-alphanumeric country code of the country where the SSN is issued.

Example data:

Field
Value
Certificate info

See above.

Header

See above.

Payload

"ref":"1234.5678.9012.3456"
"opaque":"ABCDEFGHIJKLMNOPRSTUVWXYZ012345678901234"
"ssn":"199010101010"
"country":"SE"

Final JWS (compact
format, line broken
for clarity only)

(header omitted for brevity)

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