link

# Authentication API

# Introduction

The Signicat Authentication API serves authentication through Signicat's eID hub. Methods for authentication range from public eIDs such as BankIDs and government IDs to biometric authentication for mobile apps through Signicat MobileID.

# Available protocols

Signicat supports OpenID Connect (OIDC), SAML 2.0 and SAML 1.1 (legacy). The protocols transfer the authentication as well as authorisation data in a secure way between the identity provider (like Signicat) and the service provider (the customer).

Important

SAML 1.1 is a legacy protocol and no longer being maintained. We recommend you choose OpenID Connect (OIDC) instead.

# Which protocol should I choose?

If you are in doubt, choose OpenID Connect (OIDC). This gives you easy access to Signicat and has the most common features that you need.

# OpenID Connect

This section contains some basic information about OIDC. If you want to integrate using OIDC, refer to the Getting started guide.

# The authentication URL

The URL your user is sent to for authentication typically looks as follows:

https://preprod.signicat.com/oidc/authorize?response_type=code&scope=openid+profile&client_id=demo-preprod&redirect_uri=https://labs.signicat.com/redirect&state=123abc&acr_values=urn:signicat:oidc:method:idin

The URL consist of two parts. The first part is the base URL (https://preprod.signicat.com/oidc/authorize) and the remainder constitutes parameters to set things like Client ID, Redirects and graphical profile.

# Base URL

The base URL refers to the domain and environment that you are using. By default at Signicat this is set to preprod for testing and id for production.

To achieve the best user experience and avoid confusion among end-users, Signicat recommends that you order a subdomain through Signicat, making the URL https://id.YOURDOMAIN.com instead.

# Parameters

Parameters Default value Description
response_type required code
scope required openid This determines what type of information you will get from the user. NationalID, profile, address and phone are standard scopes most commonly used.
signicat_profile optional none This sets the graphical profile being used if you have one configured through our Customer Portal.
client_id required demo-preprod The id of the OIDC client being used
redirect_uri required none This is where the user is sent after authentication
acr_values required urn:signicat:oidc:method:METHODNAME The method name is where you set which authentication method you want to use, for example sbid for Swedish BankID or nbid for Norwegian BankID. For the full list of available methods, see our identity methods overview.

# Response

The OpenID Connect protocol returns a JSON object as an OpenID response. For Swedish BankID, the response looks like this:

{
	"family_name": "Signicat",
	"given_name": "John",
	"locale": "SE",
	"name": "John Signicat",
	"signicat.national_id": "199010275312",
	"sub": "KGMyh5FBCMTkEN934sOLyyBS0rPd4-up",
	"subject.nameid.namequalifier": "BANKID-SE"
}

Usually, the unique identifier for the user is signicat.national_id, which in Sweden, Denmark and Norway is their 'personal number' (personnummer).

Last updated: 19/10/2022 15:19 UTC