Skip to content

Sign in with Microsoft Entra ID or Google Workspace

The console speaks plain OpenID Connect. Since 0.7.5 it can also read the person's groups from the provider at sign-in (Microsoft Graph for Entra ID, Cloud Identity for Google Workspace), map them to a role per Ramen group, and keep the memberships an admin set by hand next to the ones the provider decides. Roles can be your own (custom roles), and a role can insist on the provider: people who hold it cannot sign in with a password.

What has been run against real providers (0.7.5)

Microsoft Entra ID, on GKE, EKS and AKS, through a throwaway app registration and two test groups with the groups lookup on: sign-in mapped group ids to Group Admin and to an OAuth-only custom role; a person removed from a group lost that membership at the next sign-in and got it back when re-added; the bridge then signed the same person in (--oauth), and the worker listed and refused tools by that role. Google sign-in, on GKE, with the provider added on the Config page: mapped on email, same account as Entra, and the bridge's tool list followed the Google role.

In 1.0.0 (GKE, EKS and AKS): Entra ID sign-in with the groups lookup on all three mapped a group id to Group Admin on the group; on AKS, a person removed from that group got the fallback role at the next sign-in. A Google sign-in with the Cloud Identity group lookup ran on all three consoles: the lookup returned the account's groups (more than one page), and a first attempt on GKE where the lookup answered 403 was refused, because a sign-in is denied when the groups cannot be read.

Still open for Google Workspace groups: that account was a consumer Google account that belongs to Google Groups, not an account of a Workspace domain, and no sign-in applied a group → role rule to a looked-up Google group. That mapping is covered by tests against a fake endpoint only, and a Workspace-domain account has never been tried. If you run it, please open an issue.

Nothing here depends on the cloud the console runs on: Entra ID works on GKE, Workspace on EKS, both at once anywhere. A super admin sets a provider up on the Config page; environment variables remain a second source.

1. Register the console as an OIDC client

Microsoft Entra ID Google Workspace
Where Entra admin center → App registrations → New registration (web) Google Cloud console → APIs & Services → Credentials → OAuth client (web)
Redirect URI https://<console>/auth/entra/callback https://<console>/auth/google/callback
Issuer https://login.microsoftonline.com/<tenant id>/v2.0 https://accounts.google.com
Groups groups claim (Token configuration → add groups claim), or the lookup below the lookup below (Google puts no groups in the ID token); or scope on hd, the hosted domain

Then, as a super admin, Config → Identity providers (Entra ID, Google Workspace): pick the name (entra, google, or your own for any other OIDC provider), paste the issuer, client id and client secret, choose the group source, save. The secret is encrypted in the store and never shown again; the login page shows the new button at once, no restart. GET|PUT|DELETE /api/v1/config/oauth-providers/{name} is the same thing for scripts; every change is audited as config.oauth_provider.

The Identity providers card with the group source and role mapping

Config → Identity providers: an Entra ID provider with the groups lookup, and two rules on group object ids.

The environment still works, for installs that keep secrets out of the store, and shows on the card as source env (a provider saved on the page wins over the environment of the same name):

RAMEN_OAUTH_<NAME>_ISSUER=<issuer>
RAMEN_OAUTH_<NAME>_CLIENT_ID=<client id>
RAMEN_OAUTH_<NAME>_CLIENT_SECRET=<secret>
RAMEN_OAUTH_<NAME>_SCOPES=openid email profile       # optional; the lookup adds what it needs
RAMEN_OAUTH_<NAME>_GROUPS=lookup                     # 0.7.5: claim (default) | lookup

Who the person is. The account is the email the provider returns (email, or a preferred_username that is one); every MCP call then carries that account in the worker's log line, which is the accountability Ramen needs. Ramen does not ask the provider to swear the email is verified: Entra ID never sends email_verified, and 0.7.5's first live sign-in was refused for exactly that until the rule changed. A provider that returns no email at all gets an account keyed on its stable id (Entra oid in the tenant, Google sub), shown as <provider>:<id> until an email arrives. The console's public address must be the https one people use (Config → Public address, or RAMEN_PUBLIC_URL), or the provider is sent an http:// callback and refuses it (Entra: AADSTS50011).

2. Where the groups come from

claim (the default, and the only way before 0.7.5): the console reads the claim you name on the Config page from the ID token or userinfo. Entra ID can emit group ids in groups (up to 200; beyond that the token carries an overage marker and you want the lookup). Google emits no groups; hd is the domain.

lookup: after the sign-in the console calls the provider with the person's access token and injects the result as claim groups, replacing whatever the token said.

Provider Call Values you can map Scope added
entra Microsoft Graph GET /v1.0/me/memberOf (paged) every group's object id; display names too, but only when the app has GroupMember.Read.All — with User.Read alone Graph returns ids only (verified live) User.Read
google Cloud Identity groups/-/memberships:searchDirectGroups for the person's email every group's email, its groups/<id> resource name and its display name cloud-identity.groups.readonly

Set RAMEN_OAUTH_<NAME>_GROUPS=lookup or choose Group source per provider on the Config page. If the lookup fails (the API said no, or did not answer in ten seconds) the sign-in fails with 502 could not read your groups from <provider>: nobody is signed in with stale groups. For Entra ID the app registration needs Graph's User.Read delegated permission, which every registration has; if your tenant hides group membership from members, grant GroupMember.Read.All and add it to RAMEN_OAUTH_ENTRA_SCOPES. For Google, enable the Cloud Identity API on the OAuth client's project.

3. Map groups to roles per Ramen group

Config → OAuth role mapping: name the claim (groups), then add rules. Each rule is a claim value, a role and the Ramen groups it applies to. Several rules may hit one person; the highest role wins per group. A super_admin rule makes the person a super admin. Custom roles appear in the role list after the built-ins.

Claim value Role Groups
<group object id> (an Entra group's object id; the display name works only with GroupMember.Read.All) group_admin demo, analytics
<another group object id> analyst (a custom role) analytics
mcp-users@example.com (a Google group) mcp_user demo

Scoping Google Workspace without groups: claim hd, value example.com, role mcp_user in demo lets everyone in the domain connect an MCP client to demo; group admins are then set by hand on the Users page.

The same rules can come from the environment as RAMEN_AUTH_OAUTH_<NAME>_ROLE_CLAIM and RAMEN_AUTH_OAUTH_<NAME>_ROLE_MAP; rules on the Config page win per value.

4. Membership from either side

Once a claim is named, the provider's rules are re-applied at every sign-in, and they decide the memberships that came from the provider. They do not touch the memberships an admin set on the Users page:

  • A person in the Entra group AD-Analysts gets analyst in analytics from the provider. A group admin who also makes them viewer in demo by hand keeps that: the next sign-in leaves demo alone.
  • An admin entry for a group the provider also maps wins: set a person to group_admin in analytics and they stay group admin there, whatever the provider says. Remove the admin entry and the provider's role stands again.
  • Removed from the Entra group: the provider's membership is gone at the next sign-in, sessions and refresh tokens end at once (epoch bump), and the person keeps only what an admin set by hand. Ramen learns of the removal only at a sign-in: until the person signs in again, an MCP client's refresh token keeps renewing for up to RAMEN_OAUTH_REFRESH_TTL (30 days by default). To cut someone off now, Sign out everywhere (POST /api/v1/users/<id>/sign-out, 1.0.0, D92: ends their sessions, refresh tokens and live access tokens; the next sign-in applies the provider's current groups), delete the account on the Users page, or shorten that TTL.

The Users page shows the source next to each membership: via entra, set here. People whose claim values match no rule and have no admin entry see only their own account page.

5. Roles that require the provider

A custom role with OAuth only switched on (Config → Roles) refuses password and magic-link sign-in for anyone holding it in any group: /login answers 403 This account signs in with entra. MCP clients that reach the console's sign-in step land on the provider too. The bootstrap super admin is exempt, as it is from the mappings. The built-in roles cannot be made OAuth-only; make a custom one on the base you want.

6. If it does not work

Symptom Likely cause
The provider's button does not appear on the login page The provider was not saved on the Config page, or the RAMEN_OAUTH_<NAME>_* variables are not all set
Microsoft says AADSTS50011, redirect URI http://… does not match The console does not know its public https address: set Config → Public address, or RAMEN_PUBLIC_URL, to the URL people use, and register that https://<console>/auth/entra/callback on the app
Sign-in works but the account shows as entra:<id> instead of an email The provider returned no email claim; add the email optional claim on the app registration (Entra) and the account adopts it at the next sign-in
502 could not read your groups from entra Graph refused the token: the app registration lacks User.Read, or admin consent is required in your tenant. Check the audit line's tags
Sign-in succeeds but the person sees only their own account page Their groups matched no rule (ids and display names both work with the lookup; check the spelling)
A rule demoted everyone, including you Start the console with RAMEN_ADMIN_FORCE_PASSWORD=1, sign in as the bootstrap super admin, fix the rules
An existing password account signs in through the provider It is the same account, matched on the email the provider returns (verified or not); the mapping decides the provider-side memberships, the admin entries stay
A person with a custom OAuth-only role cannot sign in with a password By design; they must use the provider button
The provider does not serve the standard discovery path Point RAMEN_OAUTH_<NAME>_ISSUER at the issuer whose .well-known/openid-configuration resolves

Signing out of Ramen does not sign the person out of the provider; the next sign-in may be silent.

7. What the person gets

An MCP user signs in through the provider only to approve an OAuth client for a zone of their groups. Claude Code and the bridge do that flow by themselves; the console's login page hands off to the provider and, since 0.7.5, brings the person back to the client's consent page afterwards (next survives the round trip). After Allow, a browser that came from a native client gets a small page that sends it on to the client's loopback address (http://127.0.0.1:<port>): browsers silently drop a direct redirect from a public https page to a loopback http address, which left Claude Code and the bridge waiting for a code that never came. Web clients and scripts still get the plain 303.

Admins find the exact commands for their install on the group page: How MCP users sign in has one section per provider with the rules that reach that group, its member count, and copy-ready commands for Claude Code (over HTTP, or through the bridge) and for Cursor and VS Code through the bridge. The token the client receives carries the person's role in the group, custom roles included, so the worker can apply per-tool access to it. Connect with OAuth has the client side.