Single Sign-On (SSO) Setup

Add an OpenID Connect identity provider to FreeITSM

FreeITSM supports single sign-on via OpenID Connect (OIDC), so analysts can sign in through an external identity provider (IdP) instead of – or alongside – a local username and password.

It's a generic OIDC implementation: one configuration form works with any compliant provider, including Keycloak, Microsoft Entra ID (Azure AD), Okta, Auth0, Google Workspace and Authentik. You can configure several providers at once – handy for phased rollouts or running pilots side by side.

Want a complete worked example? The Keycloak (Docker) Setup Guide walks you through standing up a free identity provider in minutes and connecting it – the easiest way to try SSO end to end.

Before You Start

You'll need an OIDC identity provider and an application/client registered within it. From that client you need three things:

  • Issuer URL – the provider's base URL (see the issuer URL table below)
  • Client ID – the identifier of the application you registered in the provider
  • Client Secret – the secret for that application

FreeITSM reads everything else (the authorization, token, signing-key and logout endpoints) automatically from the provider's discovery document, so there's nothing else provider-specific to enter.

Step 1: Enable Single Sign-On

  1. Log in to FreeITSM as an administrator
  2. Go to System → Single Sign-On
  3. In the Global settings card, turn Enable single sign-on on, then click Save

There are two global switches here:

  • Enable single sign-on – the master switch. Turning it off instantly reverts everyone to local login (a break-glass kill switch).
  • Allow local login – keep the local username/password form available. Leave this on unless you want an SSO-only experience.

Step 2: Copy the Redirect URI

The Single Sign-On page shows a Redirect URI – the address your provider sends users back to after they sign in. Copy it (there's a Copy button) and register it in your identity provider as an allowed redirect / callback URL. It looks like:

https://your.itsm.com/api/auth/oidc_callback.php

Redirect URI Must Match Exactly

The redirect URI you register in your identity provider must exactly match the one shown on the FreeITSM SSO page – same protocol (https), domain, and path. If they differ, the provider will refuse to complete the sign-in.

Step 3: Add a Provider

Under Identity providers, click Add and fill in:

  • Display name – the label shown on the login button, e.g. Sign in with Keycloak
  • Issuer URL – your provider's base URL. Click Test to confirm FreeITSM can read its discovery document.
  • Client ID – from the application you registered in the provider
  • Client Secret – from the same application. It's stored encrypted and never shown again.
  • Scopes – leave as the default openid email profile unless your provider needs more
  • Enabled – show this provider's button on the login page
  • Auto-create users (JIT) – create an analyst automatically on first sign-in (see Step 4)
  • Default module access – modules granted to auto-created users. Leave blank and they get full access, so set this for tightly-scoped pilots.

Click Save and the provider appears in the list. You can add as many as you like.

Step 4: Decide How Accounts Are Created

When someone signs in via a provider, FreeITSM matches them to an analyst account – first by a stored identity link, then by verified email, and finally by creating one just-in-time:

  • Auto-create (JIT) on – a new analyst is created automatically the first time someone signs in. Simplest for getting started.
  • Auto-create off – only people who already have an analyst account can sign in. Best for controlled pilots.

To move an existing analyst onto SSO, open Tickets → Settings → Analysts, edit the analyst, and set their Sign-in method to the provider. Their identity links automatically (matched by email) on their next sign-in.

Strict isolation

An analyst may only sign in via the provider they're assigned to. An SSO login can never silently take over a local account or one assigned to a different provider – which keeps parallel pilots cleanly separated.

Step 5: Test the Sign-In

  1. Log out (or open a private/incognito window) to reach the login page
  2. Either type your email and click Continue (you'll be routed to your provider), or click the Sign in with … button
  3. Authenticate at the provider – you'll be redirected back and signed in to FreeITSM

Issuer URLs by Provider

The issuer URL is the one field that differs between providers. Concepts like an Entra tenant, a Keycloak realm or an Okta org all collapse into this URL:

  • Keycloak – https://<host>/realms/<realm>
  • Microsoft Entra ID – https://login.microsoftonline.com/<tenant-id>/v2.0
  • Okta – https://<org>.okta.com
  • Auth0 – https://<tenant>.<region>.auth0.com/
  • Google Workspace – https://accounts.google.com
  • Authentik – https://<host>/application/o/<app-slug>/

Break-Glass & Single Logout

  • Never locked out – local login is always recoverable. With Allow local login off the local form is hidden, but the master kill switch and a ?local=1 sign-in URL always bring it back.
  • MFA – SSO users do multi-factor at the identity provider, so FreeITSM skips its own local TOTP step for them.
  • Single logout – signing out of FreeITSM also ends the session at the identity provider.

Need a provider to test with? Follow the Keycloak (Docker) Setup Guide → it stands up a free identity provider in Docker and walks through every value above.

← Back to Getting Started