Authentication

Headless authentication

693 views July 2, 2019 July 3, 2019 0

A number of eID 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 initializes 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 eID 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 eID method set up for headless authentication through OIDC. Signicat will request some information about this setup. For more information about the setup, please refer to the OIDC documentation on the subject here.
    • If you wish to test your solution using our demo service, please 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 Authorization Request. The parameters are mostly standard OIDC parameters (you may use this guide, under ‘Crafting the Authorization URI’ as a reference). Exceptions are as follows:
    • Since this is a custom HTTP client, we recommend POSTing the authorization 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 claim. Please note that the value for this claim must be a list. For the example of Norwegian BankID, the claim to add looks like this: "login_hint": ["birthdate-ddmmyy", "phone-nnnnnnnn"].
    • The authorization request must contain the HTTP header “Accept: application/json”.
  4. Once the OIDC Authorization 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.
    1. The response will contain a session cookie. This cookie must be used in consecutive requests.
    2. 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 Authorization 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.
    • 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, and the rest of the flow is according to the OIDC standard (see “Receiving the Authorization Response” here. The “basic authorization” to use for the demo-inapp-sign OIDC client will be ZGVtby1pbmFwcDptcVotXzc1LWYyd05zaVFUT05iN09uNGFBWjd6YzIxOG1yUlZrMW91ZmE4.

A functional example of this flow can be found at https://github.com/signicat/py-inapp-auth.

The following flowchart illustrates the authentication sequence:

Important to note

  • 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. Please refer to your HTTP client’s documentation regarding how to do this.

Method-specific considerations

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

Swedish BankID Norwegian BankID
collectUrl statusUri
progressStatus status
completeUrl completeUri

Note that 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 the value returned with SwedishBankID is COMPLETE, whereas Norwegian BankID uses finished.

Was this helpful?