Introduction

Since the release of version 2020.1 of the Thinkwise platform, the combination of Indicium and IAM forms a full-fledged authentication provider that implements the OpenID Connect protocol. This means that third party applications can authenticate their users through the Thinkwise platform. Starting with the next release of Indicium Universal (2020.2.9), the Thinkwise platform also supports authenticating its users through third party authentication providers that support OpenID Connect. This makes it possible to authenticate users through Azure Active Directory, Google, GitHub, Facebook and many other authentication providers.

What is OpenID Connect

OpenID Connect is an industry standard protocol that allows for applications to delegate the authentication of users to a so-called Identity Provider. Common examples of Identity Providers are Microsoft, Google and Facebook. Whenever you see that button “Sign in with Google” on a website or an app on your smartphone, it means that the website or app is delegating their authentication of users to Google.

So just like Microsoft, Google and Facebook, the Thinkwise platform is also an Identity Provider. In fact, our Community website on which you’re reading this blog right now was made by and is hosted by a third party that delegates the authentication of you, the Community user, to Thinkwise.

Why would you want this?

From an application development standpoint, the reason could be that you don’t want to implement authentication yourself because it’s costly and difficult. However, in practice the need for this feature often comes from the customer who already has an existing user base and doesn’t want to migrate all their users to a new database or inconvenience them with registering a new account somewhere. When our Community website was developed, we already had an existing user base in TCP and we wanted our customers, partners and employees to be able to sign in with that account.

Giving and taking

Much like how we wanted a third party to delegate authentication to us, you might want us to delegate authentication to your Identity Provider. If that’s the case, then we have some good news for you. The next version of Indicium Universal (2020.2.9) will support just that. So, if you have a Microsoft Azure Active Directory with hundreds or even thousands of users or you want your users to be able to sign in with their Google account or perhaps you even want to use your own proprietary implementation, this will all be possible with the next release of Indicium Universal. However, in order to use this feature successfully, it is important to understand how it works, so please keep reading.

Authorization

So far, we have talked about authentication, i.e. proof of identity. But what about authorization? Clearly you can’t configure in Google which tables your users are or are not allowed to read in your Thinkwise application. These things can only be configured in the Thinkwise platform and are ultimately linked to the users in IAM. This means that for someone to log in with an external Identity Provider and make use of our application, there must still be a corresponding user in IAM and there needs to be something that allows us to map the external user to the user in IAM. We’ll often use the email address for this purpose, but it’s also possible to match the user ID’s in IAM with those of the Identity Provider.

Still needing to create users in IAM might feel like it defeats the purpose, but that’s not entirely true. The most painful thing about migrating users is their passwords. Typically, you can’t even obtain their passwords (or rather their hashes) in order to migrate them in the first place. But since authentication is delegated, there is no need to migrate passwords to IAM. Information like first name, last name and email address on the other hand, can easily be scripted into IAM.

How do I set up integration with an external Identity Provider?

Before we start, it is important to know that OpenID Connect defines several authentication flows and not all Identity Providers support all of them. Only Identity Providers that use the Authorization Code flow can be integrated into Indicium. This is the only flow that Indicium will use as it is the most secure and most commonly used flow.

To integrate an external Identity Provider into Indicium, all you need to do is configure a few settings in the appsettings.json. It is possible to integrate multiple external Identity Providers at the same time, as shown in the example below. Each configuration must be given a name that can be chosen freely, such as “Microsoft” and “Google” below.

"OpenIDConnect": {
  "DefaultIdentityProvider": "Google",
  "IdentityProviders": {
    "Microsoft": {
      "MetadataEndpoint": "",
      "ClientId": "",
      "ClientSecret": "",
      "ButtonIcon": "microsoft.png",
      "ButtonText": "Sign in with Microsoft"
    },
    "Google": {
      "MetadataEndpoint": "",
      "ClientId": "",
      "ClientSecret": "",
      "IncludeEmailScope": true,
      "ButtonIcon": "google.png",
      "ButtonText": "Sign in with Google"
    }
  }
}

The ButtonIcon and ButtonText properties are very straightforward, these are simply to influence what the button on Indicium’s login page looks like. The button icon needs to be stored in Indicium’s wwwroot folder.

The MetadataEndpoint refers to the OpenID Connect metadata document and will always take the form of a URL that ends with /.well-known/openid-configuration. The exact URL is determined by your Identity Provider.

The ClientId and ClientSecret properties come from the client configuration at the Identity Provider. This is very similar to how OpenID Connect clients can be registered in IAM, except now the roles are reversed. Indicium will need to be registered as an OpenID Connect client at your Identity Provider and the corresponding settings must be configured in the appsettings.

The IncludeEmailScope property is an optional property that determines if Indicium must explicitly request the email scope in order to obtain the user’s email address that will be used to map the external user to a user in IAM. Whether this setting is required depends on the Identity Provider. Azure Active Directory for instance, supplies the email address by default, but Google does not. You might wonder why the default isn’t true, but that’s because requesting the email scope might require additional configuration of permissions at the Identity Provider.

With these settings, any OpenID Connect Identity Provider can be integrated into Indicium. The screenshot below shows how it would look if you configure Microsoft and Google as Identity Providers.

It’s also possible to make the integration seamless, to avoid the need to click on a “Sign in with …” button. If you want this, then you can set one of the Identity Providers as the DefaultIdentityProvider in the appsettings.json, as was shown in the example earlier. Once set, you will no longer see Indicium’s login page, but instead it will redirect to the default Identity Provider immediately.

What’s next?

Even though we’re very happy with the state of this feature and the new capabilities that it brings to our platform, we do want to dot a few i’s and cross a few t’s in upcoming releases.

As was mentioned earlier in this blog, it is still necessary to have users in IAM that map to the external users at the Identity Provider. We understand that this is not ideal and requires some amount of manual work, especially when new users are added at the Identity Provider. In the future we want to solve this by implementing a feature called user provisioning. With user provisioning, Indicium will pull the necessary user information from the Identity Provider (with consent of the user) and create new users in IAM automatically.

We also want to add support for Proof Key for Code Exchange (PKCE). This is a security extension for OAuth 2.0, which is the protocol on top of which OpenID Connect is built. We do want to stress this doesn’t mean that anything described in this blog is currently insecure. Some Identity Providers require all clients to use this security extension, but it only improves the security of client-side applications (e.g. Javascript applications) and not server-side applications such as Indicium. Nonetheless, we will add this feature soon in order to support those Identity Providers as well.

Finally, we want to seamlessly integrate Indicium’s login page in the Universal GUI. In version 2020.2.8 of Indicium, we have already done this for our two-factor authentication pages. Soon we will do this for the entire login flow of Indicium, making all of Indicium’s authentication capabilities available to the Universal GUI.