Headless authentication

A number of ID methods, such as Swedish BankID and Norwegian BankID on mobile, support headless authentication. Headless authentication may involve authenticating the user within the merchant’s own app, but it also includes cases where a salesperson may initiate the authentication process. Through the process of authentication, merchants are able to securely authenticate the end-user according to EU regulations.

Headless authentication relies on the OpenID Connect (OIDC) protocol. Using headless authentication if you already have an existing customer relationship with Signicat is fairly easy: the necessary steps are described below.

Technical overview

The typical life cycle of a headless authentication request is:

1. The merchant determines that it must authenticate the user.
2. The merchant’s backend initialises the authentication request using OIDC.
3. Signicat relays the authentication request to the identity provider.
4. The identity provider sends a notification to the user’s mobile device.
5. The user logs in to the identity provider on their mobile device and is authenticated.

How to integrate headless authentication

These instructions are applicable to any ID method that is compatible with headless authentication, though there are some remarks that must be observed for specific methods (see the 'Method-specific considerations' section below).

1. Inform Signicat Operations that you would like to have the relevant ID method set up for headless authentication through OIDC. Signicat will request some information about this setup. For more information about the setup, refer to the OIDC documentation on the subject here.
   • If you wish to test your solution using our demo service, use Client ID demo-inapp, Redirect URI https://labs.signicat.com/redirect and method name sbid-inapp (for Swedish BankID) or nbid-inapp(for Norwegian BankID).
2. Since headless authentication does not require a web browser, you will have to do all the calls towards the Signicat OIDC API using an HTTP client. This client has two major requirements:
   • The HTTP client should support HTTP Cookies, which should persist throughout the entire authentication session.
   • The HTTP client should support and follow any HTTP redirects.
3. Begin crafting the OIDC authorisation request. The parameters are mostly standard OIDC parameters (you may use this guide, under ‘Crafting the Authorisation URI’ as a reference). Exceptions are as follows:
   • Since this is a custom HTTP client, we recommend POSTing the authorisation parameters using the application/x-www-form-urlencoded content-type towards the /oidc/authorize endpoint instead of encoding the parameters in the URI and doing an HTTP GET. This is not mandatory, however.
   • The Request must contain the user’s national identification number as a login hint.

   Important

   The value for this parameter must be a list. For the example of Norwegian BankID, the value to add looks like this: "login_hint": ["birthdate-ddmmyy", "phone-nnnnnnnn"].

   • The authorisation request must contain the HTTP Header "Accept: application/json".
4. Once the OIDC authorisation request is sent from the HTTP Client to the Signicat OIDC server, you will receive a JSON response. The exact format of the response is dependent on the method in question. Details can be found in the section on method-specific considerations below.
   • The response will contain a session cookie. This cookie must be used in consecutive requests.
   • If the JSON instead contains error and error_description attributes, something went wrong and the error_description attribute should contain valuable debugging information.
5. At this point, it is time to start polling for a result:
   • For Norwegian BankID, the polling URI is returned as a STATUS_URI in the authorisation request response. The exact format of the response is dependent on the method in question. Details can be found in the section on method-specific considerations below.
   • The status won’t be complete before the user has finished, but once the user has finished, a COMPLETE_URI attribute will also be present in the object.
6. Do an HTTP GET request towards the COMPLETE_URI provided. After a series of redirects, the HTTP client is going to arrive at the OIDC redirect URI requested in step 3 with code and state URL parameters.
   • For this call, you must NOT include the HTTP Header "Accept: application/json" but you must continue to include the session cookies.
   • The web service hosted at this redirect URI should extract the code and state query parameters from the request made by the app HTTP client. The rest of the flow is according to the OIDC standard. The "basic authorisation" to use for the demo-inapp-sign OIDC client will be ZGVtby1pbmFwcDptcVotXzc1LWYyd05zaVFUT05iN09uNGFBWjd6YzIxOG1yUlZrMW91ZmE4.

A functional example of this flow can be found on GitHub (opens new window).

The following flowchart illustrates the authentication sequence:

Important

The first response from Signicat will contain a session cookie. This cookie must be used in consecutive requests. Signicat expects the HTTP client you run on the user device to conform to the RFC 6265 standard on cookie handling. Depending on the HTTP client library you use, you might need to first enable cookies. Refer to your HTTP client’s documentation regarding how to do this.

Method-specific considerations

The following table illustrates the differences in the Authorisation response depending on the ID method used.

Swedish BankID	Norwegian BankID
collectUrl	statusUri
progressStatus	status
completeUrl	completeUri

Note

When the STATUS is not yet complete, the value returned with SwedishBankID is OUTSTANDING_TRANSACTION, whereas Norwegian BankID uses pending. When the STATUS is complete, the value returned with SwedishBankID is COMPLETE, whereas Norwegian BankID uses finished.