Integrations · OIDC

Rocket.Chat SSO

Configure Rocket.Chat Community or Enterprise to authenticate via Clavex using the built-in Custom OAuth provider. Covers username, email, and avatar synchronisation from Clavex claims.

Prerequisites

Rocket.Chat ≥ 3.0 (Community or Enterprise)
Rocket.Chat admin account
Clavex at https://id.acme.eu, org slug acme

Step 1 — Register OIDC Client in Clavex

Admin API (curl)

$ curl -X POST https://id.acme.eu/api/v1/organizations/acme/clients \ -H 'Authorization: Bearer $ADMIN_TOKEN' \ -H 'Content-Type: application/json' \ -d '{ "client_id": "rocketchat", "client_name": "Rocket.Chat", "grant_types": ["authorization_code", "refresh_token"], "redirect_uris": ["https://chat.acme.eu/_oauth/clavex"], "scopes": ["openid", "profile", "email"], "token_endpoint_auth_method": "client_secret_post" }'

Step 2 — Add Custom OAuth Provider in Rocket.Chat

Go to Admin → Settings → OAuth
Click Add custom OAuth and name it clavex

Configure the following settings:

Setting	Value
Enable	`True`
URL	`https://id.acme.eu/acme`
Token path	`/token`
Token sent via	`Header`
Identity token sent via	`Header`
Identity path	`/userinfo`
Authorize path	`/authorize`
Scope	`openid profile email`
Param name for access token	`access_token`
ID	`rocketchat`
Secret	`cs_xxxxxxxxxxxxxxxx`
Login style	`Redirect`
Button text	`Sign in with Clavex`
Button text color	`#FFFFFF`
Button color	`#1D9E75`

Step 3 — Configure Field Mapping

Still in the Clavex OAuth settings panel, expand Field map:

JSON field map

{ "name": "name", "email": "email", "username": "preferred_username", "avatar": "picture" }

Also enable:

Merge users — links existing accounts with same email
Show button on login page

Step 4 — Test

Navigate to https://chat.acme.eu and you should see a Sign in with Clavex button on the login screen.

Troubleshooting

Symptom	Cause	Fix
Button not shown on login page	OAuth provider disabled or show button setting off	Enable Show button on login page in the OAuth provider settings
`error_uri_mismatch`	Redirect URI wrong	Verify Clavex has `https://chat.acme.eu/_oauth/clavex` in redirect_uris
Username taken error on first login	Same username exists as local user	Enable Merge users setting or delete/rename the conflicting local account
Avatar not syncing	`picture` claim not present	Ensure Clavex user has a profile picture; picture URL must be publicly accessible
Login loop / state error	Cookie domain mismatch	Ensure `ROOT_URL` in Rocket.Chat matches the exact domain with protocol