Visitor Authentication with IAM

Visitor Authentication with IAM

The Scrivito SDK offers easy-to-use IAM-backed visitor authentication. This allows developers to build apps with the following features:

  • Visitor login
  • Offer additional, protected content for logged in users
  • Mandatory visitor login for the entire app (e.g. intranet)

Furthermore, the new visitor authentication offers APIs for accessing details such as the name and email address of the current visitor.

Note that visitor authentication via 3rd-party identity providers is still supported, but is considered deprecated as IAM visitor authentication provides the same functionality and new features via an API that makes integration much easier and doesn’t require a 3rd-party identity provider (IdP).

For admins and editors, there’s a guide available on how to restrict pages to logged-in visitors.

Internal vs. external users

With Scrivito, authentication supports two types of users:

  1. External users, i.e, website visitors who can log in to a Scrivito web app in order to access (additional) content or manage their own user data, for example. This guide is about how to implement support for IAM-based external users in your Scrivito web application.

  2. Internal users, i.e., editors who can log in to the Scrivito UI and may have varying additional permissions there to edit or review content, etc. Internal users can be regarded as extended external users. See also Managing Users, Teams, and Working Copy Collaborators.

Inviting external users

You can add external users to your website via the JustRelate Console. When doing this, a new user is automatically added to the “All users” team. By default, this grants the new user all the permissions needed as a visitor.

If you add an external user also to other teams, he or she additionally becomes an internal user, i.e., an editor.

What is IAM?

IAM is JustRelate’s centralized Identity and Access Management service. It provides a secure, state-of-the-art login service for users, i.e., editors and visitors, of applications built with JustRelate platform solutions such as Scrivito.

Custom identity providers

IAM also supports 3rd-party IdPs you can set up in the JustRelate Console. IAM transparently handles authentication via such IdPs.

See Setting Up Identity Providers for Your Website for further details.

Proxy setup

In order to use IAM visitor authentication, a single-page application (SPA) needs to be enabled to reach https://api.justrelate.com/iam/auth/* from its own base domain. Requests should be forwarded using the following pattern:

https://mydomain.com/auth  https://api.justrelate.com/iam/auth

This forwarding allows the browser-based application to authenticate against IAM and set a session cookie, avoiding issues related to 3rd-party cookies.

For a customer frontend application running, for example, on www.mydomain.com, a proxy is required. When forwarding requests to api.justrelate.com/iam/auth, your proxy needs to set the X-JR-Auth-Location header to pass the URL under which the proxy operates to api.justrelate.com, for example:

X-JR-Auth-Location: https://mydomain.com/auth

For IAM to accept the location, i.e. the URL, it must have been whitelisted as a “trusted origin”. You can configure trusted origins for your JustRelate account in the Scrivito Dashboard.

Please note that, for security reasons, IAM only accepts https locations.

Custom proxy locations

Custom proxy locations can be used as well. However, as the Scrivito SDK assumes that /auth is the default proxy location, custom proxy locations need to be made known to the Scrivito SDK via Scrivito.configure({ iamAuthLocation }), in addition to the proxy configuration on the server.

Development environment

For local development, IAM can be integrated into the frontend development setup using a local proxy.

Webpack

Setting up such a proxy can be done using your local dev server, e.g., DevServer | webpack.

Vite

Visitor authentication

Logging users in 

To trigger the login procedure, or to ensure that the user is actually logged in, call Scrivito.ensureUserIsLoggedIn().

This API determines whether the user is logged in. If this is not the case, it automatically redirects the browser to the log-in page. If the user is already logged in, nothing happens.

A website offering the option to log in can call this API method after a log-in button was clicked. A website requiring visitors to log in could call this method when the app initializes, for example.

Determining the log-in state

To display content, or activate some other logic, specifically for logged-in users, Scrivito.isUserLoggedIn() is available.

See the API documentation for details.

Logging users out

To trigger a logout, call Scrivito.logout().

A web app could call this method after a logout button was clicked, for example. If you use your own IdP, you can configure a URL for logging out. Otherwise, a generic logout page is shown.

Protected content

A logged-in visitor automatically has access to content protected by means of the standard (“logged_in”) visibility category, “Available to logged-in users”.