Skip to main content

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:

  1. Activate an ID method in the Signicat Dashboard.
  2. Test an authentication flow.
  3. Configure an authentication protocol.
  4. 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.

Sandbox account

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:

  1. Sign up to the Signicat Dashboard — it's free.
  2. In the Signicat Dashboard, set up an organisation and an account.
  3. 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.
Domains and eID methods

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:

  1. Go to eID Hub > ID methods.
  2. To add a new eID method, select Add new in the top right.
  3. 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.

Production account

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:

  1. Go to eID Hub > ID methods.
  2. Select Test ID method in the top right.
  3. Optional: If you've activated more than one ID method, choose Norwegian BankID from the list of available providers.
  4. Follow the steps on the BankID site and use the following test credentials:
    • National ID number: 29090816894 or 10103933108
    • One Time Code: otp
    • BankID password: qwer1234
  5. Review the user data attributes returned by BankID.
Problems with test user?

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.

The role of Signicat

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 (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:

  1. Go to eID Hub > OIDC clients and select Add client.
  2. 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 and nin are necessary in most cases. You can see the definition of profile and other predefined scopes in the OIDC specification. You find scope definitions in the specific ID methods documentation.
  3. 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 is https://verybigcorp.signicat.com, your discovery URL is https://verybigcorp.signicat.com/auth/open/.well-known/openid-configuration.
  • The issuer URL: <YOUR_SIGNICAT_DOMAIN>/auth/open/. For example, your issuer URL would be https://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.