Quick start guide
In this quick start guide, you will learn how to identify your end-users in just a few steps. For illustration purposes, we use Norwegian BankID in the examples but the same principles also apply to the other eID methods.
In this guide, you will:
- Activate an ID method in the Signicat Dashboard.
- Test an authentication flow.
- Configure an authentication protocol.
- Initiate an authentication flow with a protocol.
You'll complete steps relevant to set up an eID method in the eID Hub and prepare yourself to build your integration.
We recommend that you create a sandbox account to test our services before implementing them in a production account.
Prerequisites
To follow this guide, we assume that you've completed the following initial preparations:
- Sign up to the Signicat Dashboard — it's free.
- In the Signicat Dashboard, set up an organisation and an account.
- To use the eID Hub, you need to set up a domain. When you create a new account with Signicat, you also create your first domain. For the scope of this guide, you only need a standard Signicat domain.
Note that connecting with certain eID methods may require extra security measures, such as the use of digital SSL certificates and custom domains. You find more details in the specific eID methods documentation.
Add an eID in the Dashboard
The first step is to add and activate the eID method in your account in the Signicat Dashboard. To do this:
- Go to eID Hub > ID methods.
- To add a new eID method, select Add new in the top right.
- Choose Norwegian BankID from the list. To activate it, click Add.
Now, you can view Norwegian BankID set as "Active" in the list of eID methods.
To activate an eID method in a production account, you may need to obtain additional certificates or comply with data protection regulations. Learn more about the specific method requirements in the ID methods documentation.
Test the ID method
Once you activate an ID method, you can run a test authentication flow in the Dashboard. Testing allows you to better understand the user experience with the eID. At the end of the flow, you will view an example of attributes that contains the personal information of the test user.
To test an authentication flow in the Dashboard, do the following:
- Go to eID Hub > ID methods.
- Select Test ID method in the top right.
- Optional: If you've activated more than one ID method, choose Norwegian BankID from the list of available providers.
- Follow the steps on the BankID site and use the following test credentials:
- National ID number:
29090816894
or10103933108
- One Time Code:
otp
- BankID password:
qwer1234
- National ID number:
- Review the user data attributes returned by BankID.
The pre-generated test users for Norwegian BankID may become unavailable after many failed attempts. If this happens, try to generate a new user instead.
Connect with an authentication protocol
Signicat eID Hub provides authentication as a service, thus acting as the single point of integration between your application and the eID providers. To authenticate your end-users, you connect your application to the eID Hub using an authentication protocol.
Note that you only need to connect to the eID Hub servers. In the background, Signicat handles the connection to the eID providers separately, therefore acting as a message broker between your application and the eID providers.
Choose a protocol
The eID Hub supports the following authentication protocols:
You build your integration using one of the above protocols.
Choosing a protocol
You should choose a protocol based on what you prefer, what your application supports and what you want to achieve.
OIDC and SAML are official identity standards, while the Authentication REST API is a solution developed and maintained by Signicat.
The Signicat Authentication REST API offers a lot of flexibility and supports headless and redirect integration flow(s) (grant type).
If you want to use an official identity protocol, we recommend using OIDC. When choosing, consider the following:
- SAML 2.0 is much more complex to implement on your side since it relies on XML schemas to transmit user information and usually requires a federation agent already in place.
- OIDC is an industry standard that only focuses on authentication and based on the OAuth 2.0 standard. You send direct calls between services using REST and JSON, accessible through APIs. With OIDC you do not need to manage user sessions on your own (like with the Authentication REST API).
Set up the authentication protocol
To understand how to connect with an authentication protocol, select the corresponding tab below.
- OpenID Connect
- SAML 2.0
- Authentication REST API
OpenID Connect (OIDC)
The following sections describe how to set up authentication with OIDC. Instructions are generic and agnostic of any programming language. For a more detailed guide with language-specific examples, see the Code examples for OIDC.
Register an OIDC client
Before you can start authenticating users, you must register an OIDC client in the Signicat Dashboard. An OIDC client comes with a Client ID. Depending on the authentication grant type (flow) you want to implement, you associate a secret to the client.
To register an OIDC client in the Signicat Dashboard, do the following:
- Go to eID Hub > OIDC clients and select Add client.
- Now, configure the following properties:
- Primary grant type: Choose the grant type you want to implement. We strongly recommend AuthorizationCode. For further information about the different grant types, refer to the OIDC specification and the OAuth 2.0 specification.
- Create client from template: Optional. Choose a template to prefill your client configuration.
- Client name: Enter a name for the client.
- Redirect URI: Enter the URL where you want to redirect your end-user after they authenticate with an eID. Note that you can add several redirect URIs after you create the client.
- Scope: Select the scopes for the type of data you want to retrieve with this client.
openid
is mandatory.profile
andnin
are necessary in most cases. You can see the definition ofprofile
and other predefined scopes in the OIDC specification. You find scope definitions in the specific ID methods documentation.
- Select Create to create the new client.
Congratulations, you have created an OIDC client!
Discovery and issuer URL
Depending on how you want to implement your app, you can find:
- The discovery URL:
https://<YOUR_SIGNICAT_DOMAIN>/auth/open/.well-known/openid-configuration
. For example, if your domain ishttps://verybigcorp.signicat.com
, your discovery URL ishttps://verybigcorp.signicat.com/auth/open/.well-known/openid-configuration
. - The issuer URL:
<YOUR_SIGNICAT_DOMAIN>/auth/open/
. For example, your issuer URL would behttps://verybigcorp.signicat.com/auth/open/
.
Authenticate the end-user
To authenticate the end-user, your app must direct the end-user to the authorisation endpoint (https://<YOUR_SIGNICAT_DOMAIN>/auth/open/connect/authorize
) with the appropriate set of parameters.
https://<YOUR_SIGNICAT_DOMAIN>/auth/open/connect/authorize?
&client_id=<OIDC_CLIENT_ID>
&response_type=<GRANT_TYPE_CODE>
&redirect_uri=<REDIRECT_URI>
&scope=openid
&acr_values=<ACR_VALUES>
&state=<STATE>
Your next steps depend on the OIDC flow type you want to implement. After the end-user authenticates you can retrieve the results in the ID token and UserInfo endpoints.
Next steps
This guide introduced how the eID Hub works in a nutshell. Next, we recommend learning more about OIDC and exploring the eIDs documentation.
SAML 2.0
This guide explains how you can exchange XML metadata files with Signicat to set up a SAML 2.0 connection. To learn more about integrating using SAML 2.0, see Set up SAML.
How to exchange SAML metadata
To set up a secure connection over SAML, you must provide Signicat with a metadata file.
A metadata file contains information about the service provider (SP) and the identity provider (IdP) involved in an authentication process. For example, the metadata stores the URL of the server where to send the response after the authentication session.
To integrate your application with Signicat using SAML 2.0, you configure the metadata in the Signicat Dashboard. You can choose between these configuration options:
- Dynamic with URL: You host the metadata in your server and share the metadata URL with Signicat.
- Static with Form: You upload the metadata file in the Signicat Dashboard. If you don't have a metadata, you can fill in a form in the Dashboard and have Signicat generate (and store) the metadata file.
- Dynamic with URL
- Static with Form
To configure a dynamic metadata URL in the Dashboard, do the following:
- Go to eID Hub > SAML 2.0 and select Add new.
- Select the URL configuration method.
- Fill in the configuration. You can find information about the fields in the table below.
- Select Add to save the configuration.
- To download the Signicat metadata file in XML format, select Get Signicat's metadata.
URL configuration fields
To fetch your metadata file, we first need to check that the URL is safe. Before adding a new Metadata URL, please contact us by creating a support ticket in the Signicat Dashboard.
Required fields are marked with an asterisk (*).
Learn more about advanced configuration in the URL configuration section of the SAML 2.0 documentation.
To configure a static metadata Form in the Dashboard, do the following:
- Go to eID Hub > SAML 2.0 and select Add new.
- Select the Form configuration method.
- If you've already created your metadata file, upload it here. If not, create the metadata using the form fields described in the table below.
- Select Add to save the configuration.
- To download the Signicat metadata file in XML format, select Get Signicat metadata.
Form configuration fields
Required fields are marked with an asterisk (*).
Learn more about advanced configuration in the Form configuration section of the SAML 2.0 documentation.
Metadata file example
Here is an example of a SAML 2.0 metadata file:
<?xml version="1.0" encoding="UTF-8"?>
<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" ID="_9ef5602b6f9ed8b75334f563f91322d2"
entityID=ENTITY_ID>
<ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
XML_SIGNATURE
</ds:Signature>
<md:SPSSODescriptor AuthnRequestsSigned="true" WantAssertionsSigned="true"
protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
<md:KeyDescriptor use="signing">
<ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
<ds:KeyName>KEY_NAME</ds:KeyName>
<ds:X509Data>
<ds:X509Certificate>
X509_ENCODED_CERTIFICATE
</ds:X509Certificate>
</ds:X509Data>
</ds:KeyInfo>
</md:KeyDescriptor>
<md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
Location="https://*SP_APP_DOMAIN*/saml/acs" index="0"
isDefault="true"/>
</md:SPSSODescriptor>
<md:Organization>
<md:OrganizationName xml:lang="en">ORG_NAME</md:OrganizationName>
<md:OrganizationDisplayName xml:lang="en">ORG_DISPLAY_NAME</md:OrganizationDisplayName>
<md:OrganizationURL xml:lang="en">ORG_URL</md:OrganizationURL>
</md:Organization>
</md:EntityDescriptor>
After you have configured the SAML metadata in the Dashboard, you are ready to initialise a request for end-user authentication.
SAML authentication examples
When the end-user wants to authenticate to your services over a SAML connection, the service provider (your app) and the identity provider communicate by sending:
- A request:
AuthnRequest
- A response:
AuthnResponse
Below, you can find examples of requests and responses. For more examples, see the SAML examples.
AuthnRequest example
The SAML AuthnRequest
can be simple. You can always add more information in the request, but the request can be as minimal as the following example (POST binding):
<?xml version="1.0" encoding="UTF-8"?>
<saml2p:AuthnRequest xmlns:saml2p="urn:oasis:names:tc:SAML:2.0:protocol" AttributeConsumingServiceIndex="1"
Destination="https://*YOUR_SIGNICAT_DOMAIN*/auth/saml/login" ForceAuthn="true"
ID="_b6a016332e19a825bb42917c9870c93a" IssueInstant="2021-03-09T10:26:17.210Z"
Version="2.0">
<saml2:Issuer xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion">
ENTITY_ID
</saml2:Issuer>
<ds:Signature xmlns:ds="https://www.w3.org/2000/09/xmldsig#">
XML_SIGNATURE
</ds:Signature>
</saml2p:AuthnRequest>
The SAML AuthnRequest
request needs to be encoded for transmission. Usually, it's compressed, then Base64-encoded and finally URL-encoded. Many SAML libraries handle this automatically.
Example authorisation URL
To initiate an authentication flow using SAML, you typically redirect the end-user to the authorisation URL. Depending on the SAML binding, you send the request in a different format. For example, for POST binding you can generate an authorization URL like this:
POST https://<YOUR_SIGNICAT_DOMAIN>/auth/saml/login
and pass the following in the body of the request:
SAMLRequest
is your encodedAuthnRequest
request.RelayState
is optional and can be used to retain state information to return to after authentication.
AuthnResponse example
Example of a SAML response AuthnResponse
after the end-user logged in with eHerkenning:
<?xml version="1.0" encoding="UTF-8"?>
<saml2p:Response xmlns:saml2p="urn:oasis:names:tc:SAML:2.0:protocol" Destination="https://*SP_APP_DOMAIN*/saml/acs" ID="_8ecbe9dcd8c6e4765d5b6bd9cf5f2010" InResponseTo="_6dee7048f7b558987b5d9900e1b20832" IssueInstant="2023-12-11T12:35:48.235Z" Version="2.0" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<saml2:Issuer xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion">https://*YOUR_SIGNICAT_DOMAIN*/auth/saml</saml2:Issuer>
<ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
XML_SIGNATURE
</ds:Signature>
<saml2p:Status>
<saml2p:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success"/>
</saml2p:Status>
<saml2:Assertion xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion" ID="_03c096c04b157811ec2af48c91e4d618" IssueInstant="2023-12-11T12:35:48.263Z" Version="2.0" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<saml2:Issuer>https:/*YOUR_SIGNICAT_DOMAIN*/auth/saml</saml2:Issuer>
<ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
XML_SIGNATURE
</ds:Signature>
<saml2:Subject>
<saml2:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified" NameQualifier="urn:etoegang:HM:00000003244440010000:entities:9713">k5QDBPNavooSgsxQNCITxSnQc5oo37cqev726-Iz1-Y=</saml2:NameID>
<saml2:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
<saml2:SubjectConfirmationData InResponseTo="_6dee7048f7b558987b5d9900e1b20832" NotOnOrAfter="2023-12-11T12:37:48.263Z" Recipient="https://*SP_APP_DOMAIN*/saml/acs"/>
</saml2:SubjectConfirmation>
</saml2:Subject>
<saml2:Conditions NotBefore="2023-12-11T12:35:43.263Z" NotOnOrAfter="2023-12-11T12:37:48.263Z">
<saml2:AudienceRestriction>
<saml2:Audience>ENTITY_ID</saml2:Audience>
</saml2:AudienceRestriction>
</saml2:Conditions>
<saml2:AttributeStatement>
<saml2:Attribute Name="name">
<saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xsd:string">Gerarda Josephina Kierkegaard</saml2:AttributeValue>
</saml2:Attribute>
<saml2:Attribute Name="firstName">
<saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xsd:string">Gerarda Josephina</saml2:AttributeValue>
</saml2:Attribute>
<saml2:Attribute Name="lastName">
<saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xsd:string">Kierkegaard</saml2:AttributeValue>
</saml2:Attribute>
<saml2:Attribute Name="email">
<saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xsd:string">email@example.com</saml2:AttributeValue>
</saml2:Attribute>
<saml2:Attribute Name="pseudo">
<saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xsd:string">03659FB1FAE5D26DB2D28866C1A4FE7F4E1CD5E62DD2552EE3D3B11D4C27163D@9162F54B3B07284AC4E147A849DEAEE4</saml2:AttributeValue>
</saml2:Attribute>
<saml2:Attribute Name="kvkNr">
<saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xsd:string">24444001</saml2:AttributeValue>
</saml2:Attribute>
<saml2:Attribute Name="rsin">
<saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xsd:string">819935177</saml2:AttributeValue>
</saml2:Attribute>
<saml2:Attribute Name="serviceID">
<saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xsd:string">urn:etoegang:DV:00000003244440010000:services:9121</saml2:AttributeValue>
</saml2:Attribute>
<saml2:Attribute Name="serviceUUID">
<saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xsd:string">cf1c1457-cc97-4b47-a324-25d1a97db3cb</saml2:AttributeValue>
</saml2:Attribute>
<saml2:Attribute Name="intermediateKvkNr">
<saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xsd:string">24444002</saml2:AttributeValue>
</saml2:Attribute>
<saml2:Attribute Name="companyName">
<saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xsd:string">Signicat</saml2:AttributeValue>
</saml2:Attribute>
<saml2:Attribute Name="intermediateCompanyName">
<saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xsd:string">Intermediary</saml2:AttributeValue>
</saml2:Attribute>
</saml2:AttributeStatement>
<saml2:AuthnStatement AuthnInstant="2023-12-11T12:35:48.264Z" SessionIndex="14779d0d-08bb-4929-95a2-499363b122f7">
<saml2:AuthnContext>
<saml2:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport</saml2:AuthnContextClassRef>
<saml2:AuthenticatingAuthority>urn:etoegang:HM:00000003244440010000:entities:9713</saml2:AuthenticatingAuthority>
</saml2:AuthnContext>
</saml2:AuthnStatement>
</saml2:Assertion>
</saml2p:Response>
Next steps
This guide introduced how the eID Hub works in a nutshell. Next, we recommend learning more about SAML 2.0 and exploring the eIDs documentation.
Authentication REST API
The Authentication REST API allows you to connect to the eID Hub and perform end-user identity verification and authentication through a REST API, where all request and response bodies are formatted in JSON.
Initial preparation
The Authentication REST API supports the OAuth 2.0 client credentials grant flow: you first exchange a client ID and a secret for an access token, then use the access token to authenticate the requests to the API endpoints.
To connect to the API, you need an API Client (with a secret) configured with the correct permissions. To do this in the Dashboard, follow the instructions below:
- Set up an API Client to obtain a Client ID and a Client secret.
- Grant the correct Permissions to connect to the Authentication REST API.
To give your API client access to the API, tick the Authentication REST APIs box in the Permissions tab of your API client.
Import the Postman collection
To make calls to the Authentication REST API, we created a Postman collection. Note that Postman is a tool for learning and testing APIs, therefore you should not use Postman in your application in production.
You can fork or import the Postman collection by clicking the button below:
To start using the Postman collection, do the following:
- Fork or import the Postman collection.
- Open Postman and select the Signicat Authentication REST API collection.
- In the Variables tab, edit the following variables:
baseURL
: Enter the base URL of the API. Set this to:https://api.signicat.com/auth/rest
.oauth_scope
: Enter the scope you want to work with. Set this to:signicat-api
.oauth_client_id
: Enter the client ID (for exampledev-red-pin-123
) of your API client.oauth_client_secret
: Enter the client secret associated to your API client.oauth_url
: Enter the Authorisation URL. Set this to:https://api.signicat.com/auth/open/connect/token
.
- Click the (save) icon or type Ctrl+S.
Now, you are ready to obtain an access token using the variables you defined above.
Obtain an access token
To authorise requests to the API, you need to send an access token in your request. To obtain the access token with the Postman collection, do the following:
- Select the Authorization tab.
- Scroll to the bottom and select Get New Access Token.
- If the request was successful, review the Access Token and select Use Token.
You have now obtained a token to authenticate to the API. When calling an API endpoint, you supply the access token in the HTTP Authorization
header of your request. You can always review your token in Authorization > Token.
Note: Tokens have a default expiry date. If a token expires, repeat the steps above to request a new token.
Create an authentication session
To begin an authentication flow, your app needs to direct the end-user to an eID method, such as Norwegian BankID. To obtain the authorization URL where to redirect the end-user to authenticate, you send a POST request to the Create a new session endpoint with the appropriate parameters in the body of the request.
The body of the request might look like this:
{
"flow": "redirect",
"requestedAttributes": [
"name",
"dateOfBirth",
"nin",
],
"callbackUrls": {
"success": "https://example.com/success",
"abort": "https://example.com/abort",
"error": "https://example.com/error"
},
"allowedProviders": [
"nbid"
],
}
To begin an authentication flow using the Postman collection, do the following:
- In the left menu, expand the collection and select the Create a new session endpoint.
- In the endpoint window, select Send to send the request.
- In the response window, select the Body tab to view the response payload.
- Copy and paste the
authenticationUrl
link in your browser to start an authentication session with the eID method. In this case, Norwegian BankID.
When adding login to your application, you will redirect the end-user to the authenticationUrl
.
Authenticate the end-user
You need a test user to complete the authentication. For example, you can use the following credentials for Norwegian BankID:
After completing the authentication flow, you can retrieve the response from successful authentication.
Get the authentication session status
When using the API, you can check the status of the authentication session at any stage. When the end-user authenticates successfully, you receive the user data attributes in the response. To do this:
- In the left menu, expand the id folder and open the Get session status endpoint.
- To check the session status, select Send. This sends an HTTP GET request using the session ID obtained from the Create a new session endpoint.
- Inspect the response in the Body tab of the response window.
If the authentication was successful ("status": "SUCCESS"
), you find the end-user data attributes in the subject
field.
You have now completed an authentication flow using the Authentication REST API!
Next steps
This guide introduced how the eID Hub works in a nutshell. Next, we recommend learning more about the Authentication REST API and exploring the eIDs documentation.
For information about the available endpoints and properties, as well as sample requests and responses, see the Authentication REST API reference: