Setting up sign-in for your admins¶

This walkthrough takes an estate you run yourself, such as a KDBL Context Lake (K-Lake) proof of concept reached through a K-Lake remote-access address, from "sign in with a personal access token" to "your administrators sign in with their Microsoft Entra accounts, and their Entra groups decide who is an administrator". Every step happens on the console's Settings and AI access (MCP) pages (both in the sidebar, under ADMIN and AI ASSISTANTS), signed in as a tenant administrator. The command palette gets you to each card faster: press ⌘K (Mac) or Ctrl+K, or / when you are not typing in a field, and type the card's name. You do not need the cluster-admin token.

The example estate:


Console	`http://klake.example.internal/` (or its https address)
K-Lake's own sign-in server (the MCP address)	`https://<you>.mcp.kdbl.com`
Identity provider	Microsoft Entra ID

Console sign-in goes through K-Lake's own sign-in server. K-Lake sends each person on to Entra, and their Entra groups come back with them. The same sign-in serves AI assistants connecting over MCP, so you set up Entra once.

Who can do this

A tenant administrator of a self-managed tenant: a proof of concept or your own install, with no partner (MSP) running it. If a partner manages your tenant, Settings › Sign-in is read-only for you and says Sign-in is managed by …. Ask your partner to make the change, or to let you manage it under Who can change this tenant's sign-in.

Before you start: keep a way back in¶

Sign-in changes can lock people out, so keep a personal access token for at least one administrator. The token the installer printed for your tenant counts, and you can mint another under your own name on AI access (MCP) › Tokens (Mint token; or press ⌘K / Ctrl+K and type > then mint). A personal access token keeps working whatever the sign-in settings say. If single sign-on is ever misconfigured, paste it on the login page and put things right.

1. Register K-Lake in Entra¶

K-Lake's sign-in server needs one app registration in your Entra tenant.

In the Entra admin centre open App registrations → New registration. Name it (for example "K-Lake"), single tenant.
Authentication → Add a platform → Web. The redirect URI is shown on AI access (MCP) › Setup › Let people sign in and looks like https://<you>.mcp.kdbl.com/oauth/callback. It must match character for character.
Certificates & secrets → New client secret. Copy the value now; Entra shows it only once.
Token configuration → Add groups claim. Choose Security groups, and for the ID token emit Group ID. K-Lake then receives each person's groups as their Entra Object IDs.
Manifest: set requestedAccessTokenVersion to 2.

Then, in the console, paste the issuer (https://login.microsoftonline.com/<your Entra tenant id>/v2.0), the application (client) ID and the secret into AI access (MCP) › Setup › Let people sign in. To keep your Entra directory separate from the deployment default, use Settings › AI assistants › Sign-in › Identity provider for MCP instead. Use groups as the groups claim.

2. Find your groups' Object IDs¶

Decide which Entra groups hold your K-Lake administrators, and optionally your operators (who run sources) and warehouse administrators. For each one:

In the Entra admin centre open Groups → All groups and click the group.
On its Overview, copy the Object ID (a GUID such as 3f2b9c1e-…).

Entra sends Object IDs, not group names, so the Object IDs are what you paste into K-Lake.

Open Settings › Sign-in (or press ⌘K / Ctrl+K and type sign-in). On the Sign-in (SSO) card, open Advanced and, under Console sign-in through K-Lake's own server, click Sign the console in through K-Lake's own server. It does two things:

registers the console as a public (PKCE) client of K-Lake's sign-in server, with this console's own address plus /authn/callback as the redirect URI (for example http://klake.example.internal/authn/callback). A console on plain http is registered with a plain-http redirect, which is acceptable on a private evaluation network;
fills in the card's Issuer (K-Lake's sign-in server, https://<you>.mcp.kdbl.com), Client ID (the new client) and an API audience.

Nothing is saved yet. Review the values before you save.

If the button is missing, the card says why: the tenant is not connected to AI assistants yet (do that under Settings › AI assistants first), or it holds the deployment's main AI assistant address, where only the deployment's administrator can register clients.

To do it by hand instead, open Settings › AI assistants › Sign-in › MCP clients, press Register a client and register one with the redirect URI <console address>/authn/callback, leave Confidential unticked, and tick Allow a plain-http redirect URI when the console is on http. Then copy its client ID into the Sign-in card.

If you later move the console to https (see Console HTTPS certificate) or to a new hostname, open the console at the new address and run the helper again, then save. The old redirect URI stops matching. The HTTPS certificate page tells you whether sign-in already lists the https address.

4. The API audience is not the MCP audience¶

The API audience says which K-Lake resource the console's sign-in is for. It must be different from the MCP audience (the AI assistant audience, which the card names under the identity provider fields):

a token issued for the console carries the API audience, so it is refused at the MCP endpoint;
a token issued for an AI assistant carries the MCP audience, so it is refused by the console's API.

Keeping them apart means an assistant's token can never drive the admin console. Any stable value you will not reuse elsewhere works. The helper proposes one based on the console's address, such as https://klake.example.internal/api. Once people are signing in, leave it as it is: changing it ends every console session.

5. Groups and roles¶

On the same card, set Groups claim to groups, then open Advanced and fill in Roles from your directory:

Admin groups: the Object IDs of your administrator groups, one per line. Members are tenant administrators on every sign-in. Removing someone from the group takes the role away at their next sign-in, but K-Lake never removes the last administrator this way.
Operator groups and Warehouse admin groups: the same, for those roles.
Create a user the first time someone signs in: on, so group members get an account the first time they sign in.
Default role for new sign-ins: Reader: search and explore only, unless everyone should run sources.

See Console sign-in and roles for what each role may do.

Click Save sign-in settings (it appears once you have changed something). If the change would lock someone out, a dialog warns you first and asks you to confirm with Save anyway. It warns when:

your own session ends, because you signed in through the settings you are changing. This is expected the first time you move from a token to single sign-on;
you would lose the administrator role, because none of your groups is in the new admin groups;
no administrator could sign in afterwards. Mint a personal access token before confirming.

Then click Check issuer: it fetches the sign-in server's metadata the way the login page will, and lists anything still missing. The card's badge reads Ready once the issuer, client ID and API audience are all set, and Incomplete (naming what is missing) until then. Finally sign out (account menu at the foot of the sidebar › Sign out), and sign in again with Sign in with SSO. Your user record appears under Settings › People & access › Users and roles, marked as tenant admin if you are in an admin group.

Every change you make here is written to the tenant's admin audit log under your name.

Alternative: the console signs in with Entra directly¶

The steps above send the console through K-Lake's own sign-in server. You can instead make Microsoft Entra ID itself the console's issuer, with no K-Lake sign-in server in between.

Choose this only for console-only estates

A tenant has one issuer. With Entra as the issuer, AI assistants connecting to this tenant over MCP must also bring Entra tokens, and most assistants expect K-Lake's own sign-in server. If your people use AI assistants, use the steps above instead.

The difference that matters: Entra issues an access token for one API, chosen by the scopes the console asks for. Asked only for openid profile email, Entra issues a Microsoft Graph token, which K-Lake cannot verify, and sign-in fails. So the console registration exposes an API scope of its own, and the console asks for it.

In Entra¶

One app registration serves as both the console's client and the API it signs in to.

App registrations → New registration. Name it (for example "K-Lake console"), single tenant. Under Redirect URI choose Single-page application (SPA) and enter the console's address plus /authn/callback, for example https://klake.contoso.com/authn/callback. It must be https: Entra accepts http redirect URIs only for localhost. Do not add a client secret; the console is a public client that uses PKCE.
Note the Application (client) ID (a GUID) and the Directory (tenant) ID from the app's Overview.
Expose an API. Set the Application ID URI to the default api://<application (client) id>, then Add a scope: name access_as_user, who can consent Admins and users, with a display name and description. The full scope is api://<application (client) id>/access_as_user.
API permissions → Add a permission → My APIs, pick this app and tick access_as_user. Then Grant admin consent, so people are not asked to consent on first sign-in.
Manifest: set requestedAccessTokenVersion to 2 (accessTokenAcceptedVersion in the older manifest view). Without it, Entra issues version 1 tokens whose issuer is https://sts.windows.net/<tenant id>/, which does not match the issuer you enter below.
Token configuration → Add groups claim. Choose Security groups and, for the Access token, Group ID, so K-Lake receives each person's groups as Object IDs. Then Add optional claim → Access → email, so K-Lake receives the person's email address.

In the console¶

On Settings › Sign-in, fill in the Sign-in (SSO) card (leave the helper in step 3 alone: it is for K-Lake's own server):

Field	Value
Issuer	`https://login.microsoftonline.com/<directory (tenant) id>/v2.0`
Client ID	the application (client) ID
API audience	the application (client) ID. `api://<application (client) id>` is accepted as the same audience
Groups claim	`groups`
API scope	`api://<application (client) id>/access_as_user`

While the issuer is an Entra address the card shows these steps as a reminder. Set up the groups and roles as in step 5, save, and click Check issuer: besides the usual check, it warns when no API scope is saved and when the console is served over plain http. Then sign out and sign in with Sign in with SSO.

With these settings the console asks Entra for openid profile email api://<application (client) id>/access_as_user, and the token Entra returns carries your app as its audience, your tenant's v2.0 issuer, and the person's groups as Object IDs. App roles (the roles claim) are not used; map roles through groups.

Other identity providers: tokens must name their issuer and audience¶

Every token K-Lake accepts, from the console, an AI assistant or an upstream sign-in, must carry an issuer (iss) and an audience (aud) claim, and they must match what the tenant has configured. A token that leaves either out is refused, even if your identity provider signed it. Without an audience, a token could have been issued for any application that uses that provider.

Entra ID, Okta, Google and K-Lake's own sign-in server always include both. Keycloak leaves the audience out of access tokens unless the client has an audience mapper. To add one:

In the Keycloak admin console, open your realm › Clients › the client the console (or the AI assistant's sign-in) uses › Client scopes › the <client>-dedicated scope.
Click Configure a new mapper (or Add mapper › By configuration) and choose Audience.
Set Included Custom Audience to the tenant's API audience (or, for tokens sent to the MCP endpoint, the MCP audience). Alternatively, set Included Client Audience to a client whose ID is that value. Turn on Add to access token, and save.

To check a token, decode it (for example with jq -R 'split(".")[1] | @base64d | fromjson') and look for aud. When an identity provider leaves a claim out, the API answers 401 with the code auth.token_missing_audience or auth.token_missing_issuer and logs a warning that names the issuer.

Troubleshooting¶

Symptom	Cause	Fix
Entra says the redirect URI does not match (`AADSTS50011`)	The app registration's Web redirect is not exactly `https://<you>.mcp.kdbl.com/oauth/callback`	Copy it again from AI access (MCP) › Setup
K-Lake says `redirect_uri not registered for this client`	The console's address differs from the one the client was registered with (http vs https, IP address vs hostname)	Run the helper again from the address people use, or add that URI under Settings › AI assistants › MCP clients
You sign in but are not an administrator	The groups claim is missing, or the admin groups hold names instead of Object IDs	Check Token configuration in Entra (Group ID, ID token) and paste Object IDs
Someone in many groups loses their groups	Entra stops sending `groups` past about 200 groups and sends an overage reference instead	Emit only the groups assigned to the application (Token configuration → Groups assigned to the application). K-Lake never removes a role because the claim is absent, but it cannot grant one either
Console sign-in works but AI assistants are refused, or the other way round	The API audience equals the MCP audience	Give the console its own API audience (step 4)
Entra direct: the login page reports a token error, or every request after sign-in is refused	No API scope is set, so Entra issued a Microsoft Graph token	Set API scope to `api://<application (client) id>/access_as_user` (Entra direct)
Entra direct: Entra says the redirect URI does not match (`AADSTS50011`), or that the reply URL must use https	The SPA redirect URI differs from the console's address, or the console is on plain http	Register `<console address>/authn/callback` as a Single-page application redirect, and serve the console over https
Entra direct: Entra says the cross-origin token request needs a Single-Page Application (`AADSTS9002326`)	The redirect URI is registered under Web instead of Single-page application	Move it to the Single-page application platform
Entra direct: signed in, then refused	The token is version 1 (issuer `https://sts.windows.net/…`), or the API audience is not this app	Set `requestedAccessTokenVersion` to `2` in the manifest, and the API audience to the application (client) ID
Sign-in is refused with `auth.token_missing_audience`	The identity provider issues tokens with no audience (Keycloak without an Audience mapper)	Add an Audience mapper for the API audience (other identity providers)
Sign-in is refused with `auth.token_missing_issuer`	The identity provider issues tokens that do not name their issuer	Configure it to issue standard OIDC tokens with an `iss` claim
Locked out	A saved change stopped every administrator signing in	Sign in with a personal access token on the login page and fix the card. Failing that, ask whoever runs the deployment to use the cluster-admin token