Skip to content

Keycloak SSO with Better Auth

Overview

This guide connects a Keycloak realm directly to CloudAEye through the Better Auth SSO integration. CloudAEye supports both OpenID Connect (OIDC) and SAML 2.0.

OIDC is recommended for a new Keycloak integration. Use SAML when an existing identity-provider policy requires it.

CloudAEye supports one SSO connection and one company email domain per tenant. Users who authenticate with an email address from that domain are added to the tenant as members. SSO does not grant product access automatically.

Prerequisites

  • A CloudAEye tenant owner or administrator account.
  • A Keycloak realm with administrator access.
  • An HTTPS Keycloak URL reachable by the CloudAEye authentication service.
  • An HTTPS CloudAEye authentication API URL reachable by users' browsers and Keycloak.
  • A Keycloak user with an email address in the tenant's company domain.

In Keycloak, open the test user and confirm that Email is populated and Email verified is enabled. The email domain must exactly match the company domain configured in CloudAEye.

!!! note

CloudAEye activates the configured domain immediately. A DNS TXT record is
not required. A company domain can belong to only one CloudAEye tenant.

URLs Used in This Guide

Replace the placeholders below with values for the deployment:

Value Example
Keycloak base URL https://identity.example.com
Realm cloudaeye
OIDC issuer https://identity.example.com/realms/cloudaeye
CloudAEye auth API https://auth.example.com
Company domain example.com

If Keycloak is published under a path prefix, include it in every URL. For example, the issuer can be https://api.example.com/keycloak/realms/cloudaeye.

The OIDC discovery document must be available at:

<oidc-issuer>/.well-known/openid-configuration

The Keycloak SAML metadata document is available at:

<keycloak-base-url>/realms/<realm>/protocol/saml/descriptor

Configure OpenID Connect

Step 1: Create a Keycloak OIDC Client

  1. In Keycloak, select the realm used for CloudAEye.
  2. Go to Clients and select Create client.
  3. Set Client type to OpenID Connect.
  4. Enter a client ID, such as cloudaeye.
  5. Select Next.
  6. Enable Client authentication.
  7. Enable Standard flow.
  8. Disable Direct access grants, Implicit flow, and Service accounts roles unless another application uses them.
  9. Select Save.

CloudAEye generates a tenant-specific redirect URI. During the initial setup, add this temporary Keycloak Valid redirect URI:

<cloudaeye-auth-api>/api/auth/sso/callback/*

The wildcard is needed only to bootstrap the connection. Replace it with the exact redirect URI after Step 3.

Leave Web origins empty. The authorization-code exchange is performed by the CloudAEye authentication service, not browser JavaScript.

Step 2: Collect the OIDC Client Values

  1. Open the client's Credentials tab.
  2. Copy the Client secret.
  3. Record the client ID.
  4. Record the exact realm issuer:
<keycloak-base-url>/realms/<realm>

Do not use the discovery-document URL as the issuer. Better Auth retrieves and validates that document automatically. The issuer value returned by the document must exactly match the value entered in CloudAEye.

The Keycloak client must include the standard email and profile client scopes. They are normally assigned as default client scopes. Confirm this under the client's Client scopes tab.

Step 3: Create the CloudAEye OIDC Connection

  1. Sign in to CloudAEye as a tenant owner or administrator.
  2. Go to Settings and select Single Sign On.
  3. Select OpenID Connect.
  4. Enter the following values:
CloudAEye field Value
Company domain Bare email domain, such as example.com
Issuer URL Exact Keycloak realm issuer
Client ID Keycloak OIDC client ID
Client secret Secret from the Keycloak Credentials tab
  1. Select Create connection.
  2. Copy the generated Redirect URI.
  3. In Keycloak, replace the temporary wildcard redirect URI with this exact value and save the client.

Do not add a trailing slash or change the URL encoding. Keycloak compares the redirect URI exactly.

Configure SAML 2.0

Step 1: Collect Keycloak IdP Values

Open the Keycloak realm metadata document:

<keycloak-base-url>/realms/<realm>/protocol/saml/descriptor

Collect these values from the XML:

CloudAEye field Metadata value
IdP issuer / entity ID EntityDescriptor entityID
SSO URL SingleSignOnService Location
Signing certificate Signing X509Certificate value

Format the certificate as PEM before entering it in CloudAEye:

-----BEGIN CERTIFICATE-----
<base64 certificate from the metadata document>
-----END CERTIFICATE-----

Use the current realm signing certificate. Do not use a TLS certificate from the Keycloak load balancer or ingress.

Step 2: Create the CloudAEye SAML Connection

  1. Sign in to CloudAEye as a tenant owner or administrator.
  2. Go to Settings and select Single Sign On.
  3. Select SAML 2.0.
  4. Enter the company domain, IdP issuer/entity ID, SSO URL, and signing certificate collected from the metadata document.
  5. Select Create connection.
  6. Copy the generated ACS URL, Metadata URL, and Entity ID.

Step 3: Create the Keycloak SAML Client

  1. In Keycloak, go to Clients and select Create client.
  2. Set Client type to SAML.
  3. Set Client ID to the exact CloudAEye Entity ID.
  4. Save the client and configure these values:
Keycloak field Value
Client ID CloudAEye Entity ID
Valid redirect URIs CloudAEye ACS URL
Master SAML Processing URL CloudAEye ACS URL
Name ID format email
Force Name ID format On
Force POST binding On
Client signature required Off
Sign documents On
Sign assertions On
Signature algorithm RSA_SHA256
Encrypt assertions Off

CloudAEye requires signed assertions and validates the assertion audience, destination, response correlation, timestamps, and replay state. The audience must be the generated CloudAEye Entity ID.

Step 4: Add SAML Attribute Mappers

Open the SAML client's Client scopes or Mappers tab and add one User Property mapper for each attribute:

User property SAML attribute name Name format
email email Basic
firstName firstName Basic
lastName lastName Basic

Assign the mappers as default client scopes so they are included in every SAML assertion. Do not create duplicate mappers with the same SAML attribute name.

Test the Connection

  1. In Settings > Single Sign On, select Test sign-in.
  2. Authenticate with the Keycloak test user.
  3. Confirm that Keycloak returns to CloudAEye and the user is signed in.
  4. Sign out and test the public flow by selecting Sign in with SSO on the CloudAEye sign-in page.
  5. Enter the user's work email address and continue.

The work email selects the tenant's SSO connection. CloudAEye does not reveal whether a submitted domain is registered.

After the connection works, go to Settings > OAuth Config:

  • Enable Enterprise SSO under allowed sign-in methods.
  • Optionally enable Require SSO for the configured company domain.
  • Save the policy and test again in a private browser window.

Keep a tested tenant-owner recovery account before requiring SSO. SSO users follow the 2-step verification policy configured in Keycloak; CloudAEye's password-login 2-step verification challenge is not added to an SSO session.

Troubleshooting

OIDC Discovery Fails

  • Open <issuer>/.well-known/openid-configuration from the CloudAEye authentication service's network.
  • Confirm that its issuer value exactly matches the CloudAEye Issuer URL.
  • Confirm that all advertised authorization, token, user-info, and JWKS URLs use the externally reachable HTTPS hostname and path prefix.
  • Configure Keycloak's proxy hostname settings correctly if it is behind an ingress or reverse proxy.

CloudAEye rejects private, loopback, non-HTTPS, malformed, and mismatched OIDC issuer endpoints.

Keycloak Reports invalid_redirect_uri

Copy the active connection's Redirect URI from CloudAEye and enter it as an exact Keycloak Valid redirect URI. Remove the temporary wildcard after the exact URI works.

Keycloak Reports invalid_client

Confirm that Client authentication is enabled and that the client ID and secret in CloudAEye match the current Keycloak credentials. Recreate the CloudAEye connection after rotating the secret.

CloudAEye Reports That Sign-In Could Not Be Completed

  • Confirm that the Keycloak user has an email address and Email verified is enabled.
  • Confirm that the email suffix exactly matches the configured company domain.
  • For OIDC, confirm that the email and profile scopes are assigned.
  • For SAML, inspect the assertion and confirm that it contains one email attribute or an email-formatted Name ID.
  • Confirm that cookies are accepted throughout the redirect. Starting a second sign-in attempt can invalidate the first flow's state.

Keycloak Shows Invalid requester for SAML

Confirm that the Keycloak SAML client ID is the generated CloudAEye Entity ID, and that both Valid redirect URIs and Master SAML Processing URL contain the generated ACS URL.

SAML Signature Validation Fails

Confirm that Keycloak signs assertions with the realm key represented by the certificate stored in CloudAEye. After a realm-key rotation, reconfigure the CloudAEye connection with the new signing certificate.

Reconfigure or Disable Is Unavailable

Disable Require SSO in Settings > OAuth Config first. Then return to Single Sign On and select Reconfigure or Disable. Reconfiguring deletes the existing connection and creates a new one.

Security Notes

  • Never place the Keycloak client secret, SAML signing certificate private key, tokens, or assertions in tickets or application logs.
  • Use a confidential OIDC client and the authorization-code flow.
  • Restrict Keycloak redirect URIs to the exact generated CloudAEye URI after setup.
  • Keep Keycloak realm signing keys and OIDC client secrets on a documented rotation schedule.
  • CloudAEye supports SP-initiated SAML sign-in. IdP-initiated SAML, SAML single logout, encrypted assertions, and IdP role mapping are not part of this flow.