OIDC Settings

The OIDC Settings screen (Admin → OIDC Settings, /admin/oidc) connects this platform to your company login (single sign-on, SSO) — Keycloak, Microsoft Entra ID, Okta, Auth0 and other OpenID Connect providers. It also turns the groups of your login provider into roles of this platform.

Access requires the AUTH_MANAGE permission.

The screen has two panels: Provider Configuration on the left, Role Mappings on the right.

1. Provider Configuration

Field What it does

Auth Strategy

How users log in — see Auth Strategy

Issuer URI

The address of your login provider, for example idp.example.com/realms/myrealm. The platform reads the provider’s settings from there

Client ID

The name under which this platform is registered at your login provider

Client Secret

The secret that belongs to the Client ID. You get both from the provider

Roles Claim

The field in the login data that lists the user’s groups, for example groups or roles. The Role Mappings turn these groups into roles

Scopes

Which information the platform asks the provider for, separated by spaces. Must contain openid, otherwise the login does not work. Add email, so new accounts get a readable user name

Redirect URI Override

Leave it empty, unless the address shown below the field is wrong — see Redirect address

API Token Audience

Only for programs that use the API with a token from your login provider — see API access for SSO users. Empty: the Client ID is used

Press Save to store the configuration. You see "Saved. Restart the application for the login settings to take effect."

When a change takes effect

Field Takes effect

Issuer URI, Client ID, Client Secret, Scopes, Redirect URI Override

Only after this application is restarted

Roles Claim

At the next login of each user

API Token Audience

Immediately, no restart

Auth Strategy

Immediately for the login page — see the warning below

So the working order for SSO is: fill in the fields → Save → restart the application → test the login.

Auth Strategy

Option Login page shows

LOCAL — user name and password only

Only the form for user name and password

OIDC — company login (single sign-on) only

No form. The browser goes straight to your login provider

BOTH — password or company login

The form, and below it a button for the company login

The setting stored here is the one that counts. The AUTH_MODE setting of the installation is only used before anything was saved here.

With OIDC only, Forgot password is not offered, because users have no password here.

OIDC only really means no passwords. While the company login works, the platform refuses every user name and password — on the login page and on /api/auth/token — the admin account included. Personal API tokens (kfp_…) and the token exchange with idpToken keep working. If OIDC is selected but the company login does not work (settings incomplete, provider not reachable when the application started), passwords stay allowed so that you can still log in and fix it; the log then says so.

You can lock everybody out. The Auth Strategy changes the login page at once, but the company login itself only works after a restart with correct provider settings. If you choose OIDC while the company login is wired but your test account gets no useful roles, nobody can do anything — and the admin password is refused too.

Use BOTH while you set up SSO. Check that a company login works and gives the right roles. Only then switch to OIDC, if you want to allow only the company login.

To get back in after a lock-out, set the strategy back in the database and reload the login page (passwords work again at once, no restart needed):

UPDATE auth_config SET strategy = 'BOTH';

Redirect address

After the login, your provider sends the user back to this platform. The address it sends them to must be registered at the provider. Below the Redirect URI Override field the screen shows that address:

"Register this address at your login provider as the allowed redirect address: …"

It ends with /login/oauth2/code/…. Register it exactly as shown. If the address differs only slightly, the provider refuses the login.

The platform builds this address from how you opened the page. Behind a proxy it can be wrong, for example http:// instead of https://, or an internal host name. Then enter the correct, public address in Redirect URI Override, register the same address at the provider, and restart.

2. Role Mappings

The right panel turns groups of your login provider into roles of this platform.

Column Contents

OIDC Group / Role Name

The group name exactly as your login provider sends it

Local Role

The role users of that group get here

🗑

Removes the mapping, after you confirm with Remove

To add one: type the group name, pick a local role, click Add Mapping. Both are required.

  • The group name must match exactly, including upper and lower case. Providers send group names differently, for example ai-fabric-admins, /ai-fabric-admins, or a full path. Look at what your provider really sends, instead of guessing.

  • Several groups may point to the same role. A user in several mapped groups gets all their roles.

  • Your provider may send a single group as plain text instead of a list. Both work.

3. What happens at login

  1. The user logs in at your login provider.

  2. The platform looks for the user’s account by the provider’s unique user ID (the sub value), not by e-mail address.

  3. First login: an account is created automatically.

    • The user name is the e-mail address. Without an e-mail address it is oidc_ followed by the user ID. If the name is already taken, a short suffix is added.

    • First and last name are taken from the provider, if it sends them.

  4. Every login: the platform reads the user’s groups and looks them up in the Role Mappings.

What this means for you:

  • Your login provider decides the roles, as soon as one mapping exists. At every login the user gets exactly the roles their groups map to — no more, no less. A group removed at the provider takes the role away at the next login. Roles you set by hand under User Management are lost at the next login; change the groups or the mappings instead. The user editor says so for these users.

  • No mapped group, no roles. If none of the user’s groups is mapped, or the provider sends no groups at all, the user has no roles after the login and sees nothing; the log names the user and the groups that arrived. Create the mappings before users log in.

  • No mappings at all: then the platform leaves SSO users' roles alone, and you manage them by hand under User Management.

  • Changes reach a logged-in user at once for everything they do in the platform: each call to a Topic, GraphRAG Topic or Agent re-reads the account. A role removed by hand, or a lock, applies on the next action, without a new login.

  • Locked or disabled accounts cannot log in through the company login either. The login page shows the same message as for a wrong password. Lock the account under User Management to stop a person at once, even while their account at the provider still works.

  • E-mail changes are no problem. The same account is found by the user ID. But a user who is deleted and created again at the provider gets a new user ID — and a new account here.

  • SSO accounts have no password here. They cannot use Forgot password or Change Password.

Logging out

Logout also ends the session at your login provider, so the next person at the same browser has to log in again instead of being signed in as the previous user. For that, register this address at your provider as an allowed address after logout:

https://<address of this platform>/login

In Keycloak: client → Settings → Valid post logout redirect URIs. If your provider has no logout address (no end_session_endpoint in its discovery document), Logout only ends the session in this platform, as before. Users who logged in with a password log out as before.

4. Setting SSO up

  1. At your login provider: register a client for this platform. Note the Client ID and the secret. Make sure the login data contains the user’s groups in a field. For Keycloak, follow Keycloak: what the Keycloak admin sets up.

  2. On this screen: set Auth Strategy to BOTH. Fill in Issuer URI, Client ID, Client Secret, Roles Claim and Scopes. Save.

  3. At your login provider: register the redirect address shown on this screen, and <address of this platform>/login as the address after logout.

  4. Add the Role Mappings for every group that should have access — at least one group with a role that is useful.

  5. Restart the application.

  6. Test: log out, and log in with the company login button and a test account. Check under Admin → User Management that the account was created and has the expected roles.

  7. Optionally switch to OIDC once the company login works. The password form, including the admin account, is then no longer offered.

5. Keycloak: what the Keycloak admin sets up

Everything in this section is done in the Keycloak admin console, by whoever administers your Keycloak — not on this platform. Names are those of current Keycloak versions; older ones may label things slightly differently.

5.1 Create the client

In your realm: Clients → Create client.

Step Setting Value

General settings

Client type

OpenID Connect

Client ID

A name for this platform, e.g. knowledge-fabric — enter the same in Client ID here

Capability config

Client authentication

On (the platform keeps a client secret)

Authentication flow

Standard flow on; the others may stay off

Login settings

Valid redirect URIs

The address shown below Redirect URI Override on this screen, exactly, e.g. kf.example.com/login/oauth2/code/oidc

Valid post logout redirect URIs

kf.example.com/login — without it, Logout cannot end the Keycloak session and Keycloak shows an error page instead (see Logging out)

Web origins

May stay empty

Then open the client’s Credentials tab and copy the Client secret into Client Secret here.

The Issuer URI for this screen is <keycloak address>/realms/<realm name>, for example idp.example.com/realms/company. If you open <Issuer URI>/.well-known/openid-configuration in a browser, you must see a page of settings; if not, the address is wrong.

5.2 Send the user’s groups (required for roles)

Keycloak does not put a user’s groups into the login data by default. Without them, every company login ends up without roles as soon as one Role Mapping exists.

  1. Clients → your client → Client scopes tab → the scope named <client id>-dedicated.

  2. Configure a new mapper (or Add mapper → By configuration) → Group Membership.

  3. Set:

Setting Value Why

Name

groups

Any name

Token Claim Name

groups

Must be exactly what you enter in Roles Claim on this screen

Full group path

Off

On sends /Sales/rag-admins instead of rag-admins; the Role Mappings must then use the full path

Add to ID token

On

The browser login reads the groups from here

Add to access token

On

Needed if programs exchange access tokens at /api/auth/token

Add to userinfo

On

Harmless; some setups read it there

Using Keycloak roles instead of groups also works: use a User Realm Role or User Client Role mapper with the same settings, and map the role names here.

To check what Keycloak really sends: Clients → your client → Client scopes → Evaluate, pick a user, and look at Generated ID token. The group names there are what the Role Mappings must contain, letter for letter.

5.3 Users and groups

  • Put the people into the Keycloak groups you map on this screen. A user in no mapped group can log in but gets no roles here.

  • Disabling a user in Keycloak stops new company logins. To stop someone at once, also lock the account under User Management here: that takes effect on their next action, even in an open session.

  • Removing someone from a group takes the role away at their next login here.

5.4 Optional: programs using Keycloak tokens

For programs that trade a Keycloak token at /api/auth/token (see API access for SSO users):

  • The token must name this platform’s client: Keycloak puts the Client ID into azp of tokens issued to this client, which is enough. Tokens issued to another client need an Audience mapper on that client (Included Client Audience = this platform’s Client ID), or set API Token Audience here to what the token carries.

  • Keycloak’s access tokens are JWTs, so both the access token and the ID token can be sent.

5.5 Checklist

  • Client with Client authentication on and Standard flow

  • Valid redirect URIs = the address shown on this screen

  • Valid post logout redirect URIs = <address of this platform>/login

  • Client secret copied into this screen, Issuer URI = <keycloak>/realms/<realm>;

  • Group Membership mapper, Token Claim Name = Roles Claim here, Full group path off, Add to ID token on

  • Role Mappings here for the group names shown in Evaluate

  • This application restarted, company login tested with BOTH before switching to OIDC

6. API access for SSO users

SSO users have no password here, so they cannot get an API token with user name and password. They use the token of your login provider instead:

curl -s -X POST https://kf.example.com/api/auth/token \
  -H "Content-Type: application/json" \
  -d '{"idpToken": "<token from your login provider>"}'

The answer is the same as for a password login: a token of this platform, plus the Topics, GraphRAG Topics, Agents and Pipelines the user may use. See REST API — Obtain a token.

Which tokens are accepted:

  • The token must come from the Issuer URI above, must be signed by it, and must not be expired.

  • It must be made for this platform: the API Token Audience (or, when empty, the Client ID) must appear in the token as its audience (aud) or as the requesting client (azp).

  • It must be a JWT — a token made of three parts separated by dots. Some providers hand out access tokens that are only a random string. Those cannot be checked; send the ID token of the login instead.

The user needs the permission API_ACCESS, and the account must not be disabled or locked. The user’s groups are synced as at a normal login, if the token contains them. A token without the groups field leaves the roles as they are. If the user never logged in before, the account is created now.

Answer Meaning

200

Token issued

400

Token exchange is not set up: the Auth Strategy is LOCAL, or Issuer URI or Client ID is missing

401

The token was refused — wrong issuer, wrong audience, expired, or not a JWT. The exact reason is in this platform’s log

403

The user lacks API_ACCESS, or the account is disabled or locked

503

Your login provider could not be reached to check the token

Personal access tokens from the Profile page also work for SSO users, for the management API under /api/v1. See Management REST API.

7. Troubleshooting

Symptom Cause and fix

No company login button on the login page

Strategy is LOCAL, or the application was not restarted after the provider settings were saved, or the provider settings are incomplete

Changes to Issuer URI, Client ID, Client Secret, Scopes or Redirect URI Override have no effect

They are read at startup. Restart the application

The provider says the redirect address is not allowed

Register the address shown on this screen exactly. Behind a proxy, set Redirect URI Override and restart

Login fails at the provider

Wrong Client ID or Client Secret. Check the provider’s log

Keycloak shows "Invalid redirect uri"

The address is missing from Valid redirect URIs or differs slightly — see 5.1

Keycloak shows "Invalid parameter: redirect_uri" after Logout

<address of this platform>/login is missing from Valid post logout redirect URIs

Every Keycloak user has no roles

No Group Membership mapper, Add to ID token off, or its Token Claim Name differs from Roles Claim — see 5.2

Mappings never match although the groups arrive

Full group path is on, so the names start with / — turn it off or map the full paths

SSO login works, but the user sees nothing

No mapping matched, so the user has no roles. Add a mapping for the user’s group

A mapping exists but is not applied

The Roles Claim name is wrong, or the group name does not match exactly. Look at the login data your provider sends

Roles set by hand keep coming back to the mapped ones

Expected — roles are replaced at every login. Change the mapping

The login page is empty after switching to OIDC

The company login does not work yet. Set the strategy back to BOTH in the database (see Auth Strategy) and reload the page

Two accounts for the same person

The person’s user ID at the provider changed, for example because they were created again. Disable the old account

User name looks like oidc_a1b2c3…

The provider sent no e-mail address. Add email to the Scopes and make sure the provider sends it

API token exchange answers 401

Wrong audience, or an access token that is not a JWT. Check API Token Audience, or send the ID token

API token exchange answers 400

The Auth Strategy is LOCAL, or Issuer URI or Client ID is missing

Cannot open the screen

Your role lacks AUTH_MANAGE

Related