OpenID Connect - General Guide

If you are planning to offer Freja as an authentication method via OpenID Connect, your users must have the Freja mobile application and verify their identity in it with a valid ID document.

How to Integrate

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

Sign a contract with Freja eID Group to use OpenID Connect
Provide the following to partnersupport@frejaeid.com
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 levels of users in our API based on their account status in Freja:
  1. Basic users: lowest level of assurance, users who have only added an email to their Freja account
  2. Extended users: high level of assurance, users whom we have verified based on their valid ID document
  3. Plus users: highest level of assurance, users verified either via biometric passport or in-person meeting (only available in Sweden)
Obtain a client ID and client secret from partnersupport@frejaeid.com. This will allow you to authenticate users.

Freja 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 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

Authentication Overview

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:

Send an authorization request to Freja
After the user identifies themselves via Freja and gives consent to sharing their data, you will receive an authorization code
You need to exchange this authorization code for an access token and ID token
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

Step 1 - Sending an authorization request to Freja

Create an HTTPS GET request with the following parameters:

client id - which is received from our partner support
scope - openid is mandatory scope

Other supported scopes are:

email - returns the user's email address
profile - returns the user's full name, given name and family name
phone - user's most recently added phone number
address - returns user's postal address (if user does have an address registered)
https://frejaeid.com/oidc/scopes/age - returns the user's age
https://frejaeid.com/oidc/scopes/personalIdentityNumber - returns the user's personal identity number and country
https://frejaeid.com/oidc/scopes/allPhoneNumbers - returns all user's phone numbers
https://frejaeid.com/oidc/scopes/document - returns user's document data
https://frejaeid.com/oidc/scopes/registrationLevel - returns user's registration level in Freja (BASIC, EXTENDED, PLUS)
https://frejaeid.com/oidc/scopes/addresses - returns all user's addresses,
https://frejaeid.com/oidc/scopes/allEmailAddresses - returns all user's email addresses,
https://frejaeid.com/oidc/scopes/relyingPartyUserId- returns a unique, user-specific value that allows the Relying Party to identify the same user across multiple sessions
https://frejaeid.com/oidc/scopes/integratorSpecificUserId - returns a unique, user-specific value that allows the Integrator to identify the same user across multiple sessions regardless of the Integrated Relying Party service that the user is using
https://frejaeid.com/oidc/scopes/customIdentifier - returns a unique, Relying Party-specific, user identifier, set by the Relying Party through the REST API
https://frejaeid.com/oidc/scopes/organisationId - returns the user's organisational identifier and additional attributes

https://frejaeid.com/oidc/scopes/organisationId scope is primarily intended for users of Organisation ID. In order for a user to be able to initiate this authentication request, they must have an Organisation ID issued to them by an organisation.

Learn more about Organisation ID.

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.
user_confirmation_method - a method which user will use to confirm the login transaction (can be DEFAULT or DEFAULT_AND_FACE). Optional, default value is DEFAULT (user confirms the transaction with PIN, or biometrics configured on the phone). DEFAULT_AND_FACE requires user to do face authentication in addition to PIN when confirming the transaction.

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

The 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==

Step 2 - User identification

It is mostly up to the user to onboard, identify and approve themselves with the Freja mobile application.

Step 3 - 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:

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).
Verifying that the value of the iss claim in the ID token is equal to:
1. PROD: oidc.prod.frejaeid.com/oidc/
2. TEST: oidc-ct.test.frejaeid.com/oidc/
Verifying that the value of the aud claim in the ID token is equal to your app's client ID.
Verifying that the expiry time (exp claim) of the ID token has not expired.

Step 4 - Getting user info

User info can be obtained via an ID token or via a HTTPS GET request.

Getting user info via 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:

email,
name (full name),
given_name or family_name,
most recently added phone number,
https://frejaeid.com/oidc/claims/age (age),
https://frejaeid.com/oidc/claims/personalIdentityNumber (personal identity number),
https://frejaeid.com/oidc/claims/country (country),
https://frejaeid.com/oidc/claims/allPhoneNumbers (list of all phone numbers),
https://frejaeid.com/oidc/claims/document (user's document data),
https://frejaeid.com/oidc/claims/registrationLevel (user's registration level in Freja eID),
https://frejaeid.com/oidc/claims/organisationId (user's organisational identifier),
https://frejaeid.com/oidc/claims/organisationIdAdditionalAttributes (user's organisational additional attributes),
address (postal address - if user does have an address registered),
https://frejaeid.com/oidc/claims/addresses (all user's addresses),
https://frejaeid.com/oidc/claims/allEmailAddresses (all user's email addresses),
https://frejaeid.com/oidc/claims/relyingPartyUserId (a unique, user-specific value that allows the Relying Party to identify the same user across multiple sessions)
https://frejaeid.com/oidc/claims/integratorSpecificUserId (a unique, user-specific value that allows the Integrator to identify the same user across multiple sessions regardless of the Integrated Relying Party service that the user is using)
https://frejaeid.com/oidc/claims/customIdentifier (a unique, Relying Party-specific, user identifier, set by the Relying Party through the REST API)

Getting user info via a HTTPS GET request

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:

You will receive a JSON response that, if requested initially, will contain requested user data.

Specific formats of data received:

Document data are returned in the format described below (data is used as an example):

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

Postal address are returned in format described below:

Addresses are returned in format described below: