Purpose

The purpose of this sample project is to demonstrate how a web developer, using Auth0, can add the identity provider Verimi as an option for their end users to signup and login to his/her web application.

Auth0 Verimi authentication login integration

Photo by Fezbot2000 on Unsplash

About Verimi

Verimi is your secure ID provider.

Verimi is the trusted cross-sector European identity platform making processing digital user data easy, while identifying and verifying your users quickly and seamlessly. Verimi helps you meet your sector’s regulatory requirements in accordance with the Money Laundry Act (ZAG license by BaFin), being compliant to KYC standards as well as to European standards (GDPR, elDAS), being ISO/IEC 27001-certified and complying to the requirements of the Federal Network Agency. Verimi offers the following services: simple registration process, in-line verification, secure login, 2-FA, qualified digital signature and (soon) payment. Verimi is backed by strong partners like Samsung, Deutsche Telekom, Allianz, Axel Springer, Daimler, and Deutsche Bank.

https://verimi.de/en/

Auth0 customers can add Verimi as a custom social connection alongside other social logins. Verimi is gaining traction as an alternative to US providers for users who want Single Sign On (SSO) and greater visibility over how and where their data is shared. As an identity provider (IdP), Verimi is primarily focused on digital identity, which can help minimize the breach or misuse of data. These benefits make Verimi especially attractive to companies in Germany, where data privacy and security are paramount.

Setting up Verimi

Prerequisites

We assume that you have already registered a service provider account at Verimi. If not, you can inform yourself about the possibilities here: https://verimi.de/en/partner and contact Verimi by email, referring to Auth0: partner@verimi.com.

Configuring Verimi

  1. Verimi will send you a welcome email requesting contact data (for sending the api access data), your redirect URLs (in order to whitelist them) and your company logo (for co-branded flow)
  2. Verimi provides you with API access to the UAT test environment by email and SMS (base URL: https://verimi-uat.coretransform.com/)
  3. You test your integration and do a short acceptance test with Verimi's integration team
  4. You provide content if you want to be listed as a service provider in the customer login area
  5. Verimi will provide you with api access for the live environment (base URL: https://web.verimi.de)
  6. Verimi will coordinate joint PR and Marketing measures if you're interested
  7. You inform Verimi about the go-live date and switch your integration to live environment

This can be done within 1-2 days.

Creating a Custom Social Connection in Auth0

We assume that you already have registered an Auth0 account and setup a tenant. If not, sign up for a free Auth0 account here. Also, we assume that you already have a client app setup in Auth0. If not, you can refer to the steps and screenshots further below.

  1. Log into the Auth0 Dashboard.
  2. Go to Extensions in the left-hand menu.
  3. Make sure that the Custom Social Connections extension is installed. If not, install it by clicking on it. Creating a custom social connection in Auth0

  4. Once installed, click on the extension to configure it.

    Note: You may be asked to authenticate with Auth0 when you configure this extension for the first time

  5. The following screen shows an overview of pre-configured but disabled custom connections. Press the orange button labeled + New Connection to create and configure a new connection. Viewing available custom social connections

  6. In the configuration screen that pops up, enter the following values:

Name: Verimi

Client ID: <enter the ClientID you retrieved from Verimi>

Client Secret: <enter the Client Secret you retrieved from Verimi>

Fetch User Profile Script:

function(accessToken, ctx, cb) {
  request.get('https://verimi-uat.coretransform.com/userinfo', {
    headers: {
      'Authorization': 'Bearer ' + accessToken
    }
  }, function(e, r, b) {
    if (e) return cb(e);
    if (r.statusCode !== 200) return cb(new Error('StatusCode: ' + r.statusCode));
    var profile = JSON.parse(b);
    cb(null, {
      user_id: profile.sub,
      given_name: profile.name.split(' ')[0].trim(),
      family_name: profile.name.split(' ')[1].trim(),
      name: profile.name,
      email: profile.email,
      email_verified: profile.email_verified
    });
  });
}

Authorization URL: https://verimi-uat.coretransform.com/oauth2/auth

Token URL: https://verimi-uat.coretransform.com/oauth2/token

Scope: openid email name

Custom Headers:

Since Verimi requires Basic Authentication for authentication, but the Auth0 Custom Social Connections extension submits the credentials via post body per default, we need to create a custom header for the Authorization and add it to the configuration.

The hash is created by base64-encoding the clientID and clientSecret concatenated with a :. So the pseudo code to generate this would be:

base64encode(clientId + ":" + clientSecret)

An online base64 encoding tool can also be used to construct this value.

The full header is then constructed as per the standard authorization header format, setting the type to Bearer:

{
  "Authorization": "Basic <your base64-encoded token string>"
}

In the end, the configuration should look similar to this:

Configuring the Verimi custom social connection

You can try out the connection by pressing the Try button and, upon success, get a screen like this:

Testing the Verimi custom social connection

Under the Apps tab, make sure that your client/application is enabled for this custom social connection, otherwise enable the checkbox.

Enabling the Verimi custom social connection

After hitting the Save button and returning to the overview of custom social connections, you should see the newly added one listed and active here:

The Verimi custom connection appears in the Auth0 dashboard

Finally, adjust the Universal Login Page configuration and add a few lines of custom CSS to make the Verimi button appear with the respective logo and coloring.

In the Auth0 dashboard, go to Universal Login Page > Login and enable the Customize Login Page checkbox. Adjust the source code of the login page replacing the theme section in the JSON object with the following lines:

theme: {
  logo: config.icon,
  primaryColor: colors.primary ? colors.primary : 'green',
  authButtons: {
    "Verimi": {
      displayName: "Verimi",
      primaryColor: "#0E956E",
      foregroundColor: "#fff",
      icon: "https://raw.githubusercontent.com/auth0-blog/auth0-verimi-sample/master/img/icon.png"
    }
  }
}

Before:

The login script before making changes

After:

The login script after the CSS changes have been made

The Authentication Flow

Screencast

For more context, you can view the following screencast of the authentication flow to get a better idea of how the integration with Verimi works:

Authentication

Let's look at an example of how the login flow works in the context of a sample Angular application.

A sample application using Verimi to log in

Auth0 provides a login/signup widget with options to login/signup via username and password or via social logins, such as Verimi.

The Auth0 Lock widget showing Verimi as an option

When choosing Verimi (we're assuming the end user already has an account with them), they will be asked to log in at Verimi, providing their email address:

Logging into Verimi with an email address

They will also be asked to specify their password:

Specifying password to Verimi

Upon successful login, they will be asked to give consent to Verimi to grant Auth0 access to their personal information:

Giving consent to share segment information

Giving consent to share personal data with Auth0

Only if the service provider requests one of the scopes idcard, passport or driverlicense (i.e., personal and sensitive data), then Verimi requires the user to confirm the data transfer by 2FA via the Verimi iOS and Android apps, which can be downloaded and used for this confirmation without aborting the flow.

Waiting for login transaction confirmation via 2FA

Confirming login with personal data using 2FA

After confirmation, the demo client asks for consent to access the Auth0 tenant:

Confirming consent to access the Auth0 tenant

After consent is given, the browser redirects to the application, having received an ID token and profile information about the user:

Logged in to the demo application with an ID token

Client App Creation in Auth0

In our example, we chose a Single Page Application (SPA) based on Angular delivered from a Node.js web server. You can choose any other technology stack as well though.

In our case, the client application is created and configured as follows in the Auth0 backend:

  1. Create the application by going to the Applications section in the dashboard and click the + Create Application button. Creating a new Auth0 application

  2. Give the application any name you like and choose Single Page Web Application as the type. Selecting an application type

  3. Next, choose Angular as the technology. Selecting an application technology

  4. Afterward, you're given the choice to either integrate Auth0 into an existing app or download a complete sample. Choose the latter and download the ZIP file: Downloading the quickstart application

  5. Download and unzip the ZIP file anywhere on your computer. Then, enter a local terminal window and switch to the folder where you extracted the project into.

To build and run the project, enter:

npm install

followed by:

npm start

This should spin up a local Node.js web server, making the application available at http://localhost:3000.

Returning to the Auth0 dashboard in the browser, click the Settings tab of the app.

In the application settings:

  • set Application Type to Single Page Application.
  • set Allowed Callback URLs to http://localhost:3000/callback
  • set Allowed Logout URLs to http://localhost:3000

Configuring the application settings

As for the connections, open the Connections tab to enable any (other) connections that you want besides Verimi. Note that Custom Social Connections don't show on this screen, as they are configured within the Custom Social Connections extension itself. In our example, we chose to also offer authentication via Username-Password-Authentication, facebook and google-oauth2, besides Verimi. Thus the respective switches are enabled.

Configuring application connections for the demo app

In the end, the application is listed in the Applications overview:

Viewing the app in the Auth0 dashboard

Inspecting User Data

Once a user has authenticated, you are able to view the users list and inspect individual user data by clicking Users & Roles from the menu on the left, then selecting Users:

Viewing the list of registered users

Here you can see that the user's primary identity provider is shown as oauth2:

Inspecting user data

You can also see that the raw JSON of this user contains the Verimi identity of the user:

Inspecting the raw JSON data of the user

The Verimi Backend

After logging into the Verimi backend as a user, you can see the dashboard:

Logging into the Verimi backend

There are further options to look at your data:

Inspecting user data in the Verimi backend

As well as all your recent activities:

Inspecting recent user activity in the Verimi backend

Recap

In this post, you learned how Auth0 can help you add the German identity provider Verimi as an option for your end users to sign up and login to your web application. You saw how to configure Verimi as an Auth0 Custom Social Connection and supply all the necessary details to integrate with a Verimi application. Finally, we showed you a sample login process, and how user data can be inspected both on the Auth0 side, and within the Verimi platform.