Foreword


Your users must download the Freja eID mobile application and add their ID document to it, If you are planning to offer Freja eID as an authentication method via OpenID Connect.


Integration Steps


Below is an overview of the entire process of integration which will be explained in more detail later on:


  1. Sign a contract with Freja eID to use OpenID Connect
  2. Provide the following to [email protected]:
    1. The name of your company (100 characters maximum)
    2. The logo of your company - the ideal format would be SVG, alternatively PNG (1.5MB maximum)
    3. A brief description of your company/the services you offer both in English and Swedish (500 characters maximum)
    4. The URL you wish to be displayed to users in Freja eID e.g. your website
    5. The redirect URI where your users will land after a successful authentication
    6. The min registration level of a user required when approving transaction, will be used for all transactions, if it is not set in request.
      We differentiate between 3 types of users based on assurance of the user's identity.
      1. Basic - for users who have only registered with an email address
      2. Extended - for users whose identity was verified with an ID document
      3. Plus - for users whose identity was further verified with a physical meeting in addition to an ID document (only available in Sweden)

  3. Obtain a client ID and client secret from [email protected]. This will allow you to authenticate users.


Freja eID OpenID Connect Metadata


OpenID Connect allows the use of a JSON document found at a well-known location containing key-value pairs that provide details about the OpenID Connect provider's configuration, including the URIs of the authorization, token, userInfo, and public-key endpoints.


Freja eID metadata URLs:


Production environment: oidc.prod.frejaeid.com/oidc/.well-known/openid-configuration

Customer Test environment: oidc-ct.test.frejaeid.com/oidc/.well-known/openid-configuration


Overview of how Authentication Works


Authenticating the user involves obtaining an ID token and validating it. ID tokens are a standardised feature of OpenID Connect designed for use in sharing identity assertions on the Internet.


The most commonly used approaches for authenticating a user and obtaining an ID token are called the 'authorization code' flow and the 'implicit' flow. Of these two, the 'implicit' flow is not supported.


The 'authorisation code' flow allows the back-end server of an application to verify the identity of the person using a browser or mobile device. This document describes how to set up this flow for authenticating users.


Below is an overview of the process, and each authentication stage will be explained in further detail afterwards:

  1. Send an authorization request to Freja eID
  2. After the user identifies themselves via Freja eID and consents to sharing their data, you will receive an authorization code
  3. You need to exchange this authorization code for an access token and ID token
  4. Depending on your setup, you can get user info in two ways:
    1. Obtain user info from the ID token
    2. Send a new request to user_endpoint for user information


Sending an authorization request to Freja eID


Create an HTTPS GET request with the following parameters:


        Example URL with multiple scopes in request: [...]scope=openid%20profile%20email[...]

  • redirect uri - HTTP endpoint on your server that will receive the response, it must be the same as the one you provided to our support otherwise an error will be returned
  • nonce - a random value generated by your app that enables replay protection and will be returned as a part of ID token
  • state - a random value generated by your app that will be returned together with code in the response
  • response type - should be code for this flow
  • min registration level - required registration level of a user (can be BASIC, EXTENDED or PLUS). Optional, if set it will be used only for one request.

The endpoint URI can be found in our metadata as authorization_endpoint value.


Below is an example of an authorization request with placeholder values (compact format, line broken for clarity only).

GET /authorize HTTP/1.1

Location: https://oidc.prod.frejaeid.com/oidc/authorize?

  response_type=code
  &scope=openid%20profile%20email
  &client_id=s6BhdRkqt3
  &nonce=af0ifjsldkj
  &state=c3RhdGVfZXhhbXBsZQ==
  &redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb
  &min_registration_level=EXTENDED

Response will contain code which is exchanged for token in the next request.
Below is an example of the response.

HTTP/1.1 302 Found
Location: https://client.example.org/cb?
  code=gBBzwxxc5qm4ETcDXCqTLN
  &state=c3RhdGVfZXhhbXBsZQ==

User identification


When it comes to the second step from above, it is mostly up to the user to identify and approve themselves with the Freja eID mobile application.


Exchanging the authorization code for the access token and ID token


The response will include a code parameter, a one-time authorization code that your server can exchange for an access token and ID token. The validity period of the authorization code is 5 minutes.


Your server makes this exchange by sending an HTTPS POST request to the token_endpoint which you can find in our metadata as the token_endpoint value. The request must include the following parameters in the POST body:

  • code - authorization code received from the previous request
  • client_id - received from our partner support
  • client_secret - received from our partner support
  • redirect_uri
  • grant_type - must be authorization_code, as defined in the OAuth 2.0 specification

In response, you will receive id_token and access_token. The validity period for the ID token is 1 hour and for the access token it is 10 minutes.


Below is an example of get token request with placeholder values (compact format, line broken for clarity only).

POST /token HTTP/1.1
  
Host: https://oidc.prod.frejaeid.com/oidc/token
Content-Type: application/x-www-form-urlencoded
 
  grant_type=authorization_code
  &code=gBBzwxxc5qm4ETcDXCqTLN
  &client_id=s6BhdRkqt3
  &client_secret=secret
  &redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb


When you receive a response to the above, you can validate the ID token by:

  1. Verifying that the ID token is properly signed by the issuer - tokens are signed using one of the certificates found at the URI specified in the jwks_uri metadata value. This validation requires retrieving and parsing certificates, and making the appropriate cryptographic calls to check the signature (see jwt.io).
  2. Verifying that the value of the iss claim in the ID token is equal to:
    • PROD: oidc.prod.frejaeid.com/oidc/
    • TEST: oidc-ct.test.frejaeid.com/oidc/
  3. Verifying that the value of the aud claim in the ID token is equal to your app's client ID.
  4. Verifying that the expiry time (exp claim) of the ID token has not expired.


Getting user info


User info can be obtained from an ID token. The ID token is a JWT (JSON Web Token) i.e. a cryptographically signed Base64-encoded JSON object. 

If requested initially, it will contain the user's:


Another way of getting user info is by sending an HTTPS GET request to the userInfo endpoint that can be found in our metadata as the userInfo_endpoint metadata value. The request must include the following parameters in the header:

  • Authorization - value; Bearer access_token received in the previous request

Below is an example of get user info request with placeholder values.

GET /userinfo HTTP/1.1

Host: https://oidc.prod.frejaeid.com/oidc/userinfo

Authorization: Bearer eyJraWQiOiJqd2tfc2lnbmluZ19rZXkiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJBOUQyMjZENjQw
RkYxODhGODUxRkYzNUE4NjBFNjk3QjZFOTQ5QTZBREE1MTRFRTRDNjM3RURBQjY1MEJ
EMEQ1IiwiYXpwIjoib2lkYy1pbnRlZ3JhdGVkIiwiaXNzIjoiaHR0cHM6XC9cL2JlbGxpbTQ1LnRl
c3QudmVyaXNlYy5zZVwvb2lkY1wvIiwiZXhwIjoxNjAxNjQ1MDExLCJpYXQiOjE2MDE2NDQ0
MTEsImp0aSI6IjliMTgxYjQxLWY2YjgtNDBjNi05YmNkLWM3MGU1NjVkNThlMCJ9.kxn6kHR
pQjE6zFdSAbi19IF9XwwAErilpjg1J7-dbkruxU_639hIEe0g-
XSn7NgDBK1qJ2xtbALKlIIWz7IMzZNLdf-
6VyANRbeimKMXlT0XUQGDoOCQqfsEQJycUR08E6fb8oP6WuIchDxxai2HLMhUd6hqXXB
EwEG89fsT_l3WxwmOfZMGYJvTV-HqIfvStmOs1DrAVLsaeSRso6-
XMx0GqSccjjJFNnuqtbqIBFsjFMPOpMyHAG8yC0Lz32pXF9kAOrhrjto0d0CzpKWLWeNHrO
L2aaPO4Q7fLnTyCw0hnM-vzZkWn07F5_6GhjFvvwf2Xkgbr4OGcINL_GFieA


You will receive a JSON response that, if requested initially, will contain the user's:

User's covid certificate data will be returned in format described bellow:

"https://frejaeid.com/oidc/claims/covidCertificate" : {
    "vaccines": {         
              "certificate": "base45encodedCertificate"  },
    "tests": {         
              "certificate": "base45encodedCertificate"  },
    "recovery": {         
              "certificate": "base45encodedCertificate"  }
}

User's document data will be returned in format described bellow (data is used as an example):

"https://frejaeid.com/oidc/claims/document" : {
      "type": "PASS",
      "country": "SE",
      "serialNumber": "123456789",
      "expirationDate": "2025-10-12"
}

Possible values for document type are:

- "PASS" - Passport
- "DRILIC" - Driving licence
- "NATID" - National ID
- "IDSIS" - SiS certified ID document
- "TAXID" - Tax Agency ID card
- "OTHERID" - Other IDs

User's postal address will be returned in format described bellow:

"address": {
        "country": "SE",
        "city": "city",
        "postCode": "post code",
        "address": "address"
    }

User's addresses will be returned in format described bellow:

 "https://frejaeid.com/oidc/claims/addresses": [
    {
      "country": "SE",
      "address": "address",
      "city": "city",
      "postCode": "post code",
      "type": "RESIDENTIAL/POSTAL"
    }
  ]