# About authentication

This document provides some conceptual information about authentication:

Differences between an integration using the REST API and one using OIDC.
Differences between the flows available on the REST API.
Description of the authentication process from the end-user's point of view.

All the information here applies to version 2 of the Authentication API. If you want to migrate from v1 to v2, use this migration guide.

# REST API or OIDC?

You can integrate with Signicat in two ways, either by connecting to our REST API, or by using OpenID Connect. Each integration method has different features, so your use case will dictate which option is the best for you.

# About the REST API

Several authentication flows: redirect, headless, and iframe. See more below.
Native mobile app experience for some methods (thanks to the headless flow).
Signicat Express SDKs.
For further information about the REST API, see this video tutorial.

# About OIDC

Industry standard being used by some of the biggest players in technology, such as Google and Facebook.
Easily available libraries for different languages and frameworks.
No need to manage user sessions on your own.
For further information about OIDC, see this video tutorial.

# Authentication flows on the REST API

When creating a new session with the REST API, a flow must be specified. Which flow to use depends on how you want to integrate the authentication session in your application or website. Below, we present a short description of each flow, as well as their pros and cons and how to use them.

# Redirect

In a redirect flow, the end-user must be redirected to the url that is returned from the API when creating a new session (top-level navigation in the browser). After completing the session, the end-user will be redirected back to your website.

# Pros

Easy to implement
The user knows where they are entering their login information (since the URL is visible in the browser's address bar).

# Cons

The user has to leave your website to authenticate.

Example request

{
  "flow": "redirect",
  "redirectSettings": {
    "successUrl": "https://example.com/success",
    "abortUrl": "https://example.com/abort",
    "errorUrl": "https://example.com/error"
  }
}

# Iframe

In an iframe flow, you embed the urlreturned from the API in an iframe on your own website. A message is dispatched to the parent window (the one hosting the iframe) when the session is completed, so some Javascript is required in order to receive the dispatch message (see below for an example).

# Pros

The user does not leave your website, the authentication feels like part of your website.

# Cons

Some ID providers don't allow iframes, which means that a pop-up will have to be used. This concerns, for example, MitID and social logins such as LinkedIn, Google, or GitHub.
Pop-ups will be displayed in a new tab on mobile devices. This can be confusing and cause users to get stuck on the new tab.

How to receive dispatch messages

When using the iframe flow, messages are sent to your page with postMessage (opens new window) when a session is either successful, aborted or failed due to an error. The URI of the parent window must match the URI that is specified in iframeSettings.postMessageTargetOrigin when the session is created.

You must listen to the dispatched messages by registering an event listener:

window.addEventListener('message', function(event) {
  if (event.origin !== 'https://id.idfy.io')
    return;
  
  const data = JSON.parse(event.data);
  console.log(data.status); // => 'success/aborted/error'
});

It is important to validate the origin before processing the message because the message handler accepts messages from any URI.

The origin is https://id2-test.idfy.io for our test environment, and https://id.idfy.io for production.

TIP

We are in the process of moving all of our services to *.signicat.io domains. To make sure that your application is ready for this change, please include https://id-test.signicat.io (test environment) and https://id.signicat.io (production environment) as valid origins.

The message object has the following structure:

{
  "sessionId": "<sessionId>",
  "status": "<success/aborted/error>"
}

Example request

{
  "flow": "iframe",
  "iframeSettings": {
    "parentDomains": ["https://secure.wayneenterprises.com"],
    "postMessageTargetOrigin": "https://secure.wayneenterprises.com"
  }
}

# Headless

There is no UI involved in the headless flow, so you will not get a url from the API when creating a session. In a headless flow, the ID provider is automatically started on the end-user's device. Since there is no UI, all required information about the end-user must be sent in the API request when creating the session (e.g. date of birth and phone number, for Norwegian BankID on mobile). You must poll the API in order to know when the end-user has completed the session. This is done by calling the /sessions/<sessionId> endpoint every few seconds.

# Pros

You have full control over the UI on your end.
Since no browser is required, this is a great fit for mobile apps.

# Cons

Headless authentication only works with Norwegian BankID on mobile and Swedish BankID.

Example request

{
  "allowedProviders": [
    "no_bankid_mobile"
  ],
  "flow": "headless",
  "prefilledInput": {
    "phoneNumber": "+4799887766",
    "dateOfBirth": "1983-12-07"
  }
}

# User experience

From the point of view of the end-user, the authentication process has three main steps:

Choose which identity provider to authenticate with.
Enter the data required by the identity provider.
End of the authentication process. If using the REST API, this step will be different depending on the chosen flow. For example, if using the redirect flow, it is at this point that the user is redirected to the defined URL.

The images below show what the authentication process looks like when using Norwegian BankID, as an example.

← Overview Quick start guide →