Navigation

20.16. Connect Keycloak for Staff Single Sign-On

Connect your Keycloak realm, configure staff login-domain routing, and verify sign-in to existing AlgaPSA accounts.

20.16. Connect Keycloak for Staff Single Sign-On
Connect your Keycloak realm, configure staff login-domain routing, and verify sign-in to existing AlgaPSA accounts.
20. IntegrationsUpdated: 11/15/2026

Use Keycloak / OpenID Connect to let staff authenticate through your own Keycloak realm. It is available in Community and Enterprise Edition. Staff identities are matched by email to existing AlgaPSA accounts; this integration does not create users.

Before you begin

  • Create the staff accounts in AlgaPSA and confirm that their email addresses match their Keycloak identities.
  • Use an internal administrator account with system_settings:update permission.
  • Have the Keycloak server URL, realm, client ID, and client secret ready, plus access to configure the client in that realm.
  • Keep a working administrator sign-in available while validating the setup.

Configure Keycloak / OpenID Connect

  1. Open Settings > Security > Single Sign-On and find Keycloak / OpenID Connect.
  2. Create a confidential OpenID Connect client in your Keycloak realm and allow the redirect URI displayed in AlgaPSA.
  3. Complete these fields:
FieldWhat to enter
Keycloak server URLThe public server URL, for example https://keycloak.example.com. Enter the realm separately.
RealmThe realm name exactly as it appears in Keycloak.
Client IDThe ID of the confidential client created for AlgaPSA.
Client secretThe client's secret. On later edits, leave it blank to keep the saved secret.
  1. Select Verify and save. AlgaPSA checks the realm's OpenID discovery endpoint and verifies its issuer before saving. The issuer combines the server URL and realm, for example https://keycloak.example.com/realms/northpoint.
  2. Expand Advanced: custom identity provider routing and add your staff login domain. In Enterprise Edition, claim and verify that domain; Community Edition uses domain registration without ownership verification.
  3. Test sign-in with an existing staff member's email address. The Keycloak button appears only when provider discovery succeeds and returns Keycloak for that login. If it does not appear, review the saved realm configuration and login-domain routing.

Figure 1: Configure the tenant's Keycloak realm under Security > Single Sign-On.

Verify staff sign-in

Test with an existing staff account whose email domain matches the routing you configured. Confirm that Sign in with Keycloak opens the intended realm and returns to the correct AlgaPSA staff account.

For example, an MSP using the fictional northpoint.example domain should test with an existing staff identity from that domain before asking its entire team to change their sign-in routine.

Figure 2: Keycloak appears as a sign-in option when provider discovery offers it for the login.

Successful Verify and save checks the realm's discovery document and issuer. It does not prove that every staff account's email, login-domain routing, or client configuration is correct. Complete an actual sign-in before enabling a required-SSO policy. See Staff sign-in policy.

Deployment defaults

For a deployment-wide fallback, configure KEYCLOAK_URL, KEYCLOAK_REALM, KEYCLOAK_CLIENT_ID, and KEYCLOAK_CLIENT_SECRET on the server. A complete tenant-specific realm configuration takes precedence; otherwise, provider discovery can use the deployment's Keycloak configuration.

Resolve setup problems

SymptomCheck
The realm does not answer OpenID discoveryConfirm the server URL and realm name, and that the AlgaPSA server can reach the realm.
The reported issuer does not matchUse the public server URL configured in Keycloak; enter the realm in its separate field.
The Keycloak button is missing for a staff emailCheck the saved realm configuration and staff login-domain routing, including domain verification in Enterprise Edition.
An identity cannot reach the expected accountConfirm that the AlgaPSA internal user exists and that its email matches the Keycloak identity.

When updating a saved configuration, leave Client secret empty to retain the stored secret. Enter a replacement when rotating the client secret, then verify and test sign-in again.

Google and Microsoft account linking and staff sign-in policies remain covered in Single sign-on management.