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:
| Thing | Value used in this guide | Where it must match |
|---|---|---|
| Keycloak realm | company | Keycloak URL, Bichon Issuer URL |
| Client ID | mail-archive | Keycloak client, Bichon Client ID |
| Test user | alice / alice@company.example | Keycloak user |
| Keycloak address | http://<KEYCLOAK_HOST>:8080 | Browser and Bichon server |
| Bichon address | http://<BICHON_HOST>:15630 | Browser |
Do not use
bichonas the Client ID. The client is the Bichon application inside Keycloak; calling itbichonmakes it hard to tell the client ID apart from the product name.mail-archiveis used here for that reason.
What you are building
- The user opens Bichon's sign-in page and clicks SSO Login.
- Bichon sends the browser to Keycloak.
- The user signs in with their Keycloak account.
- Keycloak sends the browser back to Bichon with a one-time code.
- 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:rootoruser: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-devWhat the parts mean:
KC_BOOTSTRAP_ADMIN_USERNAME/KC_BOOTSTRAP_ADMIN_PASSWORDcreate the temporary administrator account.KC_HOSTNAMEmust be the same address users and Bichon use. A mismatch produces confusing "issuer" errors later.-v keycloak-data:/opt/keycloak/datakeeps realms and clients when the container is recreated. Without it, everything is lost when the container is replaced.start-devis for testing. See Production notes before going live.
Check that Keycloak is up:
curl -s http://<KEYCLOAK_HOST>:8080/realms/master/.well-known/openid-configurationYou 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.
- In the Keycloak admin console, open the realm dropdown in the top-left corner (it currently says master).
- Click Create realm.
- Realm name:
company. - Click Create.
- 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.
-
Left menu → Clients → Create client.
-
General settings:
Field Value Client type OpenID ConnectClient ID mail-archiveName Bichon Mail ArchiveClick Next.
-
Capability config:
Setting Value Why Client authentication ON Bichon sends a client secret when exchanging the login code Standard flow ON The browser redirect flow Bichon uses Direct access grants OFF Not used by Bichon Service accounts roles OFF Not used by Bichon Click Next.
-
Login settings — use the exact address users type to open Bichon:
Field Value Valid redirect URIs http://<BICHON_HOST>:15630/api/auth/oidc/callbackValid post logout redirect URIs http://<BICHON_HOST>:15630/sign-inWeb origins http://<BICHON_HOST>:15630Click Save.
-
Open the Advanced tab and set:
Setting Value Proof Key for Code Exchange Code Challenge Method S256Click Save.
-
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
-
Left menu → Users → Create new user.
-
Fill in:
Field Value Username aliceEmail alice@company.exampleEmail verified ON First name / Last name any value -
Click Create.
-
Open the Credentials tab → Set password:
- Password: for example
Passw0rd! - Temporary: OFF (otherwise Keycloak forces a password change on first login)
- Password: for example
-
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 field | Value | Notes |
|---|---|---|
| SSO enabled | ON | The sign-in page button appears after a reload |
| Issuer URL | http://<KEYCLOAK_HOST>:8080/realms/company | This is the realm URL. Do not paste the admin console URL and do not append /.well-known/openid-configuration |
| Client ID | mail-archive | The Client ID from Step 3, not the Client name |
| Client secret | the value copied from Credentials | Treat it like a password |
| Redirect URI | http://<BICHON_HOST>:15630/api/auth/oidc/callback | Must be character-for-character identical to the Valid redirect URI in Keycloak |
| Allowed email domains | company.example or empty | Optional. 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-inin 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
- Open Bichon in a new incognito window.
- Open the sign-in page. The SSO Login button should be visible.
- Click it. The browser goes to Keycloak.
- Sign in as
alicewith the password from Step 4. - You are returned to Bichon and signed in.
Check the result:
- Users page: a new user
alicewas 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.loginentry 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:
| Claim | Where it comes from | How Bichon uses it |
|---|---|---|
sub | ID token | The stable identity of the user. Stored as the SSO ID and checked first on every later login |
email | UserInfo, or the ID token | Links an existing Bichon user by email; also used by the optional allowed-domain check |
preferred_username | ID token | Local username when a new user is created (falls back to the email prefix, then to the sub value) |
name | ID token | Not stored |
picture | UserInfo | Not 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.
| Message | What it means | What to do |
|---|---|---|
| Connection successful | Bichon reached Keycloak and read the configuration | Click Save configuration |
| The address was not found | The realm or path is wrong | Check 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 port | Keycloak is not listening there | Check docker ps, the -p 8080:8080 mapping, and any firewall |
| Bichon cannot find the server | The host name is wrong or not resolvable | Use the IP address or a DNS name the Bichon server can resolve |
| The connection timed out | Network or firewall blocks the request | Check the route between the Bichon host and Keycloak |
| The HTTPS certificate is not trusted | Certificate problem | Use a certificate the Bichon server trusts, or HTTP for local testing |
| The address redirects to another address | A proxy or HTTP-to-HTTPS redirect | Use the final address shown in the details |
| The provider reports a different address | KC_HOSTNAME or the proxy changes the address | Use the address reported by the provider as the Issuer URL |
| The address did not return login-provider settings | You pasted an admin or login page, not the realm URL | Use .../realms/<realm>, not .../admin/... |
Errors after clicking SSO Login appear on the Bichon sign-in page:
| Message | Likely cause |
|---|---|
| SSO Login button missing | SSO is off, the form is incomplete, the license is not Pro, or the page was not reloaded |
invalid_client in Keycloak | Wrong client secret, or Client authentication is off in Keycloak |
Invalid redirect URI in Keycloak | The Valid redirect URI and Bichon's Redirect URI differ (scheme, host, port or path) |
id_token_invalid | The Issuer URL does not match what Keycloak reports, or the server clock is wrong |
| Email domain not allowed | The user's email is not in the Allowed email domains list |
| License required | The 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
localhostfor 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
- Keycloak → Clients → mail-archive → Credentials → Regenerate.
- Copy the new secret.
- 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
Securerequire HTTPS. - Set
KC_HOSTNAMEto 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.