Setting Up Identity Providers for Your Website

Setting Up Identity Providers for Your Website

With the Web Interface Builder SDK 1.41.0 and later, it is no longer required to set up a custom identity provider (IdP) for visitor authentication. See Visitor Authentication with IAM for details. However, it is still possible to use custom IdPs.

  • If you already have a custom IdP which you would like to use, follow step 2 of this tutorial.
  • If you want to set up a new custom IdP – which should not be necessary in most cases – this article provides an overview of how to proceed.

Apart from  Visitor Authentication with IAM, the Interface Builder still supports legacy visitor authentication (now deprecated) which requires a custom IdP.

This article covers the IdP setup for both types. If you are implementing the latter one, follow the instructions in the boxes titled Legacy auth below.

  • Visitors logged in to an Interface-Builder-based website can open pages that have been marked as restricted.

    Editors are required to log in to get access to the Interface Builder’s editing interface. They can authenticate using an identity pro­vider.

With the Interface Builder, you can give visitors to your website as well as the editors working on your content the possibility to log in via an identity provider (IdP) that supports OpenID Connect, e.g., Auth0 or Google.

In this guide, we are going to show you how to set up identity providers and make them known to your Interface Builder, via the JustRelate Console.

The Console is JustRelate’s account management tool where you can set up and maintain, for example, the users and teams, IdPs, API keys, and other details related to your Interface-Builder-based website. Like all services from JustRelate, the Console uses JustRelate’s unified identity and access management (IAM) service for authorizing editors. Even though visitor and editor authentication are two completely different stories, setting them up is almost identical, so they are both covered here.

If the navigation of your Console doesn’t include an “Identity Providers” section, please have it enabled by our Support.

What are identity providers?

An identity provider (IdP) offers user authentication as a service. For service providers, the main benefit of using IdPs is that the identity of users can be asserted without the need to store and manage their accounts and passwords.

Most people come into contact with identity providers when they click on login form buttons such as “Log in with Google”, for example. For users, it is convenient to be able to bypass login forms, and to not have to maintain dedicated credentials for a further service.

The Interface Builder works with any identity provider supporting OpenID Connect. You can even connect your own Active Directory or LDAP, as long as they’re configured for OpenID Connect.

Why OpenID Connect?

OpenID Connect is a widely used authentication service supported by several major cloud platform providers such as Google, Microsoft, or Yahoo. So any person with an account at any of these providers can be added as a website visitor or editor to a Interface Builder instance.

OpenID Connect is based on the OpenID 2.0 and OAuth 2.0 protocols. OpenID Connect directly incorporates OAuth 2.0 capabilities. These components are open standards, so you can be confident that your visitors and editors are logged in securely.

General procedure

For your website to support logging in via a visitor identity provider, three steps need to be made:

  1. Register your website with the IdP.
  2. Register the IdP in the JustRelate Console. You can register up to twenty IdPs.
  3. Implement Visitor Authentication with IAM in your website.
Legacy auth
  1. Register your website with the IdP.
  2. Register the visitor IdP in your Scrivito Dashboard.
  3. Add a log-in form to your website that lets visitors authenticate via the IdP(s)

Afterwards, only logged-in visitors are given access to website content that is flagged as restricted. Below, we will guide you through the first two steps, the registrations. Making your website fit for logging in via the IdP is covered by the corresponding API documentation linked above.

To set up an editor identity provider, only two steps are required:

  1. Register your website with the IdP.
  2. Register the IdP in your Console.

Using the Console, CMS admins and chief editors can add (invite) users as visitors or editors to the CMS, who can then log in to the corresponding website. Once a user has logged in, they are redirected to the Interface Builder application.

Step 1: Setting up GSuite or Auth0 as the identity provider

GSuite as the identity provider

In this section, we will be using Google GSuite as our identity provider. Please refer to Google’s OpenID Connect Guide for further details. Further down, we’ll walk through the same setup using Auth0 as our IdP.

First, open the “Credentials” page in the Google API Console. On the “OAuth consent screen”, fill out the form and make sure to enter “scrivito.com” in the “Authorized domains” input field.

Next, click “Create credentials” and select “OAuth client ID”.

GSuite: Create an OAuth client ID for Interface Builder login

On the next screen, select “Web Application” as the “Application Type”, give your new Google OAuth client a name, and provide the Interface Builder’s authentication callback URL. This piece of information can be found in the “Identity providers” section of your account in the Console (requires the “Manage configuration” permission):

JustRelate Console: “Identity providers” section providing the "Authentication Callback URL" for copying

Copy the authentication callback URL and paste it into Google’s “Authorized redirect URIs” input field.

Google OAuth client: Enter the Interface Builder's callback URLs as authorized redirect URLs

Next, click “Create” on the Google OAuth client setup page. Make a note of the client ID and secret, as you will need them in step 2:

  • Client ID, e.g. JLSyTv8ReKff8zxz2PdNqkfUpJ37qg6u.apps.googleusercontent.com
  • Client Secret, e.g. 2Tz9kqRaTLLAgTh8m8YAMN6P

Next, jump ahead to step 2 and make your identity provider known to your Interface Builder.

Auth0 as the identity provider

Here, we will be using Auth0 as our identity provider with OpenID Connect support.

For configuring Auth0 as an identity provider, open the Auth0 dashboard and create an application. Make sure to select the “Single Page App” type for visitor authentication, and “Regular Web App” for editor authentication. Then, from the settings tab of the new application, take down the following data as you will need it in step 2 to make your identity provider known to the Interface Builder:

  • Domain, e.g. example.eu.auth0.com
  • Client ID, e.g. JLSyTv8ReKff8zxz2PdNqkfUpJ37qg6u
  • Client Secret …
Auth0’s “Settings” tab showing "Domain", "Client ID" and "Client Secret"

For an editor identity provider, Auth0 needs to be provided with the Interface Builder’s authentication callback URL. This piece of information can be found in the “Identity providers” section of your website in the JustRelate Console. Copy this URL and paste it into Auth0’s “Allowed Callback URLs” input field.

If the navigation of your Console doesn’t include an “Identity providers” section, please have it enabled by our Scrivito Support.

Console: "Authentication Callback URL" for copying

Step 2: Making your identity provider known to your Interface Builder

So far, you have set up an application with your IdP. To complete the process, let’s configure the Interface Builder to use this IdP for authenticating users.

To add an identity provider, open the JustRelate Console in your browser, select the “Identity providers” section (requires the “Manage configuration” permission), and enter the details there.

JustRelate Console: Adding an editor identity provider
Legacy Auth

To add a visitor identity provider, open the Dashboard in your browser, select the “Settings” tab of your website, and enter the details in the “Visitor Identity Providers” section.

Dashboard: “Settings” tab, section “Visitor Identity Providers”

Up to 20 identity providers can be configured. The Interface Builder accepts logins from any of the providers. For each of them, the following pieces of information are required:

  • Provider URL: This is the “Domain” value from above, specified as a complete URL, including the HTTPS scheme. For the “example.eu.auth0.com” example domain, the provider URL would be “https://example.eu.auth0.com/”. For Google as the IdP, it’s always “https://accounts.google.com”.
  • Client ID: The client ID you were given in the IdP setup process.
  • Client Secret: The client secret you were given. Only required for IdPs using the HS256 algorithm (see below).
  • Hosted Domains: With Auth0 as your IdP, this field can be left blank because the provider URL already contains your unique account name, “example”, as part of the domain. For Google, however, use your GSuite domain name. If your GSuite includes multiple domains, you can specify up to ten of them as a comma-separated list.
  • Logout URL: After a user has logged out from the Interface Builder, they are still logged in with the IdP, and would be logged in automatically the next time they visit the website because of the automatic OAuth handshake between the Interface Builder and the IdP. If you are worried that this may irritate the users, you can also log them out from the IdP whenever they log out from the Interface Builder. For this, specify a logout URL to which the Interface Builder should redirect for logging the user out from the IdP as well.
Legacy Auth

A logout URL is not required for visitor IdPs.

There are two algorithms identity providers use to generate and validate the signature of a JSON Web Token (JWT), HS256 and RS256. While the HS256 algorithm requires a client secret, RS256 doesn’t (as it is asymmetric), and thus the corresponding field in the Console can be left empty for IdPs using RS256.

With this, we are done with editor authentication. For visitors, your app needs to implement Visitor Authentication with IAM.

Specifying an IdP when logging in as an editor

As a default, when logging in to an Interface-Builder-based website as an editor, the Interface Builder uses the first editor identity provider from the ones configured in your Console.

With several editor IdPs configured, this default can be overridden by specifying the one to select using the _scrivito_idp URL parameter, like so:

https://my.website.com/scrivito?_scrivito_idp=https://my.website.idp.com

If you have many websites or support various identity providers, we recommend editors to bookmark the URLs they use most frequently for logging in.

Additional information for IdP admins

The Interface Builder requires the OpenID Connect IdP to be used to support the openid, email and profile scopes. From these scopes, the Interface Builder uses the following claims:

ScopeClaims used
openid
hd, iss, sub
email
email, email_verified
profile
name, picture

In case email, email_verified and name aren’t already included in the ID token, the Interface Builder fetches these values from the IdP’s “userinfo” endpoint. The URL of this endpoint is provided via the “userinfo_endpoint” key in the IdP’s “.well-known/openid-configuration” data. See Google’s OpenID configuration for an example.