Skip to main content

​
Single Sign-On

mogenius supports Single Sign-On (SSO) through OpenID Connect (OIDC), allowing team members to authenticate using their existing identity provider accounts. Once configured, your organization receives a unique login page that you share with your team.

​
Supported Providers

  • Microsoft Entra ID (formerly Azure Active Directory)
  • GitHub
  • OpenID Connect — any standards-compliant OIDC provider (GitLab, Okta, Keycloak, Auth0, and others)

​
How the connection works

You configure SSO under Organization settings → Single sign-on. When you select a provider, the form shows a Redirect URI for your organization — copy it and register it in your identity-provider app. The provider validates this value exactly, so it must match including the trailing slash:
After you enter the provider credentials and click Connect, mogenius displays a Login URL for your organization. Share this URL with your team — users who sign in via this link are added to your organization automatically.

​
Microsoft Entra ID

All steps happen in the Microsoft Entra admin center of your own tenant. First decide how mogenius should learn about your users’ groups — the steps differ:

​
Step 1: Register the application (both modes)

  1. App registrations → New registration. Any name; supported account types: Accounts in this organizational directory only.
  2. Authentication → Add a platform → Web. Set the Redirect URI to the value shown in the mogenius SSO form. The trailing slash is required.
  3. Certificates & secrets → New client secret. Copy the secret Value immediately — it is shown only once.
  4. Overview. Note the Application (client) ID and the Directory (tenant) ID.

​
Step 2a: Group memberships via Microsoft Graph

  1. API permissions → Add a permission → Microsoft Graph → Delegated → GroupMember.Read.All.
  2. Grant admin consent for <tenant>. The row must show Granted. Adding the permission alone is not enough — users would see “Approval required” at sign-in.
  3. App roles → Create app role. Allowed member types Users/Groups; values admin, editor, viewer (further values are passed on as workspace roles).
  4. Enterprise applications → <app> → Users and groups → Add user/group. Assign each group an app role. Only assigned groups are synced.
  5. Organization roles: groups named mogenius-admin, mogenius-editor, or mogenius-viewer set the organization role; their app role is ignored.
Assigning groups to enterprise applications requires Entra ID P1. The app reads its own role assignments by itself, so no application permission is needed.

​
Step 2b: Group memberships via token claims

  1. Token configuration → Add groups claim. Select Security groups; keep Group ID for the ID token. (Manifest equivalent: "groupMembershipClaims": "SecurityGroup".)
  2. Token configuration → Add optional claim → ID: email, given_name, family_name (recommended for complete profiles).
  3. API permissions: the default User.Read is enough — no admin consent.
  4. Groups → <group> → Overview → Object ID. Note the object ID of every group that should grant workspace access.
  5. In the cluster, create a GroupGrant per group (see Group-based workspace access).
Organization roles are not derived from Entra in this mode — reserved group names don’t match object IDs. Manage them in mogenius. If a user belongs to more than ~200 groups, Entra omits the groups claim; choose Groups assigned to the application and assign the relevant groups under Enterprise applications → Users and groups (Entra ID P1).

​
Step 3: Connect in mogenius

  1. Organization settings → Single sign-on → Microsoft Entra. Choose Group memberships (Microsoft Graph or Token claims), enter the Client ID, Client Secret, and Tenant ID, then click Connect.
  2. Members sign in through the organization’s Login URL. Group changes take effect at the next sign-in.

​
Both modes

  • Users must be members of a group — owners do not count.
  • The Redirect URI needs the trailing slash.

​
GitHub

  1. In GitHub, go to Settings → Developer settings → OAuth Apps → New OAuth App (in your personal account or an organization).
  2. Fill in the details:
    • Application name: A recognizable name (e.g., “mogenius SSO”)
    • Authorization callback URL: Paste the Redirect URI from the mogenius SSO form
  3. Register the app, then generate a client secret.
  4. Back in mogenius, select GitHub, enter the Client ID and Client Secret, and click Connect.

​
OpenID Connect

Use the generic OpenID Connect provider for any standards-compliant OIDC identity provider — for example GitLab (including self-hosted instances), Okta, Keycloak, or Auth0.
  1. In your provider, create an OIDC/OAuth application:
    • Redirect URI: Paste the Redirect URI from the mogenius SSO form
    • Scopes: openid, email, profile
    • Where applicable, mark the application as confidential.
  2. Note the Client ID, Client Secret, and the provider’s Issuer URL — the base URL where its discovery document lives at <issuer>/.well-known/openid-configuration (for example https://gitlab.com for GitLab.com, or your self-hosted base URL).
  3. Back in mogenius, select OpenID Connect, enter the Client ID, Client Secret, and Issuer URL, then click Connect.
For self-hosted providers, make sure the instance is reachable on a public HTTPS hostname. mogenius needs the discovery URL to be publicly accessible.

​
Group-based workspace access

With a GroupGrant, an identity-provider group maps to access on a workspace (or cluster) with a specific role. In the token-claims flow you reference the group by its object ID; with name-based groups you reference the group name.
role is optional. A GroupGrant saved without a role defaults to viewer (applied for kubectl/GitOps as well as the UI/CLI), so a forgotten role never grants more than read access. Members who receive access through a GroupGrant appear in the workspace member list marked as SSO group. Their role is managed in the identity provider / GroupGrant, not per user in mogenius.

​
Troubleshooting

Redirect URI mismatch error Ensure the Redirect URI in your identity provider exactly matches the one shown in mogenius, including the protocol (https://) and the trailing slash. Discovery failures (self-hosted OpenID Connect) Verify that your provider is reachable from the internet and that <issuer>/.well-known/openid-configuration returns a valid JSON document. Instances behind a VPN or on a private IP cannot be used. Missing email in user profile Ensure the email scope (or, for Entra, the email optional claim) is included, and that users have a verified email address in their identity provider.