Bichon Docs
Pro EditionSingle Sign-On

This guide walks through a complete Keycloak setup for Bichon, from starting Keycloak to signing in with a test user. It assumes no prior Keycloak experience. Every field you need to copy is listed explicitly.

The names used in this guide are examples. Use your own values, but keep the same value everywhere it appears:

ThingValue used in this guideWhere it must match
Keycloak realmcompanyKeycloak URL, Bichon Issuer URL
Client IDmail-archiveKeycloak client, Bichon Client ID
Test useralice / alice@company.exampleKeycloak user
Keycloak addresshttp://<KEYCLOAK_HOST>:8080Browser and Bichon server
Bichon addresshttp://<BICHON_HOST>:15630Browser

Do not use bichon as the Client ID. The client is the Bichon application inside Keycloak; calling it bichon makes it hard to tell the client ID apart from the product name. mail-archive is used here for that reason.

What you are building

  1. The user opens Bichon's sign-in page and clicks SSO Login.
  2. Bichon sends the browser to Keycloak.
  3. The user signs in with their Keycloak account.
  4. Keycloak sends the browser back to Bichon with a one-time code.
  5. Bichon verifies the code and creates or links the local user.

Nothing is shared except the client ID and client secret you configure below.

Before you start

  • Bichon Pro or Enterprise is running (a trial counts), and you can sign in as an administrator (system:root or user:manage).
  • Keycloak 26 or newer is available (Docker is enough).
  • You know the address users will use to open Bichon in a browser, for example http://192.168.1.60:15630.
  • You know the address both the browser and the Bichon server can use to reach Keycloak, for example http://192.168.1.50:8080.
  • For a first test, plain HTTP is fine. For production, use HTTPS on both sides.

The Bichon server itself must be able to reach the Keycloak address (it fetches the provider configuration and exchanges the code). Do not use localhost for Keycloak unless Bichon and the browser are on the same machine.

Step 1 — Start Keycloak

On the machine that will run Keycloak:

docker run -d --name keycloak \
  -p 8080:8080 \
  -e KC_BOOTSTRAP_ADMIN_USERNAME=admin \
  -e KC_BOOTSTRAP_ADMIN_PASSWORD='ChangeMe-123!' \
  -e KC_HOSTNAME=http://<KEYCLOAK_HOST>:8080 \
  -v keycloak-data:/opt/keycloak/data \
  quay.io/keycloak/keycloak:26.4 start-dev

What the parts mean:

  • KC_BOOTSTRAP_ADMIN_USERNAME / KC_BOOTSTRAP_ADMIN_PASSWORD create the temporary administrator account.
  • KC_HOSTNAME must be the same address users and Bichon use. A mismatch produces confusing "issuer" errors later.
  • -v keycloak-data:/opt/keycloak/data keeps realms and clients when the container is recreated. Without it, everything is lost when the container is replaced.
  • start-dev is for testing. See Production notes before going live.

Check that Keycloak is up:

curl -s http://<KEYCLOAK_HOST>:8080/realms/master/.well-known/openid-configuration

You should get JSON containing "issuer":"http://<KEYCLOAK_HOST>:8080/realms/master". Then open http://<KEYCLOAK_HOST>:8080 in a browser and sign in as admin.

Step 2 — Create the realm

A realm is an isolated space for users and clients. Bichon needs its own realm.

  1. In the Keycloak admin console, open the realm dropdown in the top-left corner (it currently says master).
  2. Click Create realm.
  3. Realm name: company.
  4. Click Create.
  5. Make sure the dropdown in the top-left corner now says company. All following steps happen inside this realm.

If you skip step 5, you will create the client or user in the wrong realm. Check the top-left corner before every step.

Step 3 — Create the client

The client is the entry for Bichon inside Keycloak.

  1. Left menu → Clients → Create client.

  2. General settings:

    FieldValue
    Client typeOpenID Connect
    Client IDmail-archive
    NameBichon Mail Archive

    Click Next.

  3. Capability config:

    SettingValueWhy
    Client authenticationONBichon sends a client secret when exchanging the login code
    Standard flowONThe browser redirect flow Bichon uses
    Direct access grantsOFFNot used by Bichon
    Service accounts rolesOFFNot used by Bichon

    Click Next.

  4. Login settings — use the exact address users type to open Bichon:

    FieldValue
    Valid redirect URIshttp://<BICHON_HOST>:15630/api/auth/oidc/callback
    Valid post logout redirect URIshttp://<BICHON_HOST>:15630/sign-in
    Web originshttp://<BICHON_HOST>:15630

    Click Save.

  5. Open the Advanced tab and set:

    SettingValue
    Proof Key for Code Exchange Code Challenge MethodS256

    Click Save.

  6. Open the Credentials tab and copy the Client secret.

Three things are easy to confuse:

  • Client ID is mail-archive (a name you chose).
  • Client name is only a display label; Bichon does not use it.
  • Client secret is the random value under Credentials. It is not the Client ID and not your Keycloak password.

Step 4 — Create a test user

  1. Left menu → Users → Create new user.

  2. Fill in:

    FieldValue
    Usernamealice
    Emailalice@company.example
    Email verifiedON
    First name / Last nameany value
  3. Click Create.

  4. Open the Credentials tab → Set password:

    • Password: for example Passw0rd!
    • Temporary: OFF (otherwise Keycloak forces a password change on first login)
  5. Click Save.

Bichon only needs the user's email. A user without an email address cannot be matched by the optional domain allow-list and will be rejected when that allow-list is enabled.

Step 5 — Fill in Bichon

In Bichon: Settings → Single Sign-On. This page requires system:root or user:manage and a Pro/Enterprise license.

Fill in the form exactly:

Bichon fieldValueNotes
SSO enabledONThe sign-in page button appears after a reload
Issuer URLhttp://<KEYCLOAK_HOST>:8080/realms/companyThis is the realm URL. Do not paste the admin console URL and do not append /.well-known/openid-configuration
Client IDmail-archiveThe Client ID from Step 3, not the Client name
Client secretthe value copied from CredentialsTreat it like a password
Redirect URIhttp://<BICHON_HOST>:15630/api/auth/oidc/callbackMust be character-for-character identical to the Valid redirect URI in Keycloak
Allowed email domainscompany.example or emptyOptional. Leave empty while testing

Click Test connection. You should see Connection successful. If not, see Troubleshooting. Then click Save configuration.

The SSO button on the sign-in page is loaded from the server. Open /sign-in in a new incognito window (or reload the page) after saving; an already-open session may still show the old sign-in page.

Step 6 — Test the login

  1. Open Bichon in a new incognito window.
  2. Open the sign-in page. The SSO Login button should be visible.
  3. Click it. The browser goes to Keycloak.
  4. Sign in as alice with the password from Step 4.
  5. You are returned to Bichon and signed in.

Check the result:

  • Users page: a new user alice was created by Bichon.
  • It has the default Member role and no account access. Assign account access or roles in Bichon as you would for any user.
  • Audit log: an sso.login entry was written.
  • Sign out: the browser returns to Bichon's sign-in page, and the Keycloak session is ended as well.

Bichon does not import Keycloak groups or roles. Access inside Bichon is controlled by Bichon roles, not by Keycloak roles.

What Bichon reads from Keycloak

Bichon requests the standard scopes openid email profile. It uses these claims:

ClaimWhere it comes fromHow Bichon uses it
subID tokenThe stable identity of the user. Stored as the SSO ID and checked first on every later login
emailUserInfo, or the ID tokenLinks an existing Bichon user by email; also used by the optional allowed-domain check
preferred_usernameID tokenLocal username when a new user is created (falls back to the email prefix, then to the sub value)
nameID tokenNot stored
pictureUserInfoNot used. The Bichon avatar stays empty; upload one under Settings → Profile

Bichon does not check email_verified today. The identity provider is trusted to only authenticate real users.

Troubleshooting

Start with Test connection on the SSO settings page. It reports one of these categories in plain language, and the technical details can be expanded below the message.

MessageWhat it meansWhat to do
Connection successfulBichon reached Keycloak and read the configurationClick Save configuration
The address was not foundThe realm or path is wrongCheck the realm name in the top-left corner of Keycloak; the URL must end with /realms/company. Modern Keycloak has no /auth prefix
The server was found, but nothing is running on that portKeycloak is not listening thereCheck docker ps, the -p 8080:8080 mapping, and any firewall
Bichon cannot find the serverThe host name is wrong or not resolvableUse the IP address or a DNS name the Bichon server can resolve
The connection timed outNetwork or firewall blocks the requestCheck the route between the Bichon host and Keycloak
The HTTPS certificate is not trustedCertificate problemUse a certificate the Bichon server trusts, or HTTP for local testing
The address redirects to another addressA proxy or HTTP-to-HTTPS redirectUse the final address shown in the details
The provider reports a different addressKC_HOSTNAME or the proxy changes the addressUse the address reported by the provider as the Issuer URL
The address did not return login-provider settingsYou pasted an admin or login page, not the realm URLUse .../realms/<realm>, not .../admin/...

Errors after clicking SSO Login appear on the Bichon sign-in page:

MessageLikely cause
SSO Login button missingSSO is off, the form is incomplete, the license is not Pro, or the page was not reloaded
invalid_client in KeycloakWrong client secret, or Client authentication is off in Keycloak
Invalid redirect URI in KeycloakThe Valid redirect URI and Bichon's Redirect URI differ (scheme, host, port or path)
id_token_invalidThe Issuer URL does not match what Keycloak reports, or the server clock is wrong
Email domain not allowedThe user's email is not in the Allowed email domains list
License requiredThe Pro license is missing or expired

Common mistakes

  • Using the admin console URL as the Issuer URL. It must be the realm URL: http://<KEYCLOAK_HOST>:8080/realms/company.
  • Creating the client in the master realm instead of company.
  • Putting the Client name in Bichon instead of the Client ID.
  • Pasting the client secret with a trailing space, or using a secret from another client.
  • Using localhost for Keycloak while Bichon runs on another machine or in a container.
  • Opening Bichon over HTTPS while Keycloak (or the image URL) is HTTP. Browsers block this; use HTTPS for both.
  • Forgetting to reload the sign-in page after enabling SSO.
  • Changing the realm or client in Keycloak and not updating Bichon.

Rotating the client secret

  1. Keycloak → Clients → mail-archive → Credentials → Regenerate.
  2. Copy the new secret.
  3. Bichon → Settings → Single Sign-On → paste it into Client secret → Save configuration.

No restart is needed. Existing sessions stay valid until they expire.

Several Bichon instances

Create a separate client per Bichon instance (for example mail-archive-prod and mail-archive-test). Each gets its own redirect URI and secret.

If you really need one client for several instances, add every callback URL to Valid redirect URIs, but remember that rotating the secret affects all of them at once.

Production notes

  • Use HTTPS for both Bichon and Keycloak. Browsers block mixed HTTP/HTTPS content, and cookies marked Secure require HTTPS.
  • Set KC_HOSTNAME to the public address, and make sure the reverse proxy forwards the original host and scheme (X-Forwarded-Host / X-Forwarded-Proto).
  • The address in the Issuer URL must be reachable from both the browser and the Bichon server.
  • Keep the client secret out of tickets, chat and screenshots. Bichon stores it encrypted, but anyone who has it can impersonate the client.
  • Restrict Valid redirect URIs to the exact Bichon callback URL. Never use a wildcard.
  • Disable Direct access grants (already done in Step 3). Bichon never uses password grants.
  • Consider the optional Allowed email domains list to prevent accounts from other domains being provisioned.

On this page