SSO Integration

Mezite integrates with your identity provider (IdP) so your team can authenticate with their existing corporate credentials and receive short-lived SSH certificates. SSO attributes are mapped to Mezite roles and user traits, driving RBAC policy without manual user provisioning. This guide covers OIDC, SAML 2.0, LDAP/AD, and GitHub OAuth.

How SSO Flows into Certificate Issuance

The SSO login flow results in a short-lived SSH certificate issued by Mezite's User CA. No static SSH keys are involved.

1. User initiates login — The user runs msh login --auth=<connector-name> (passing the SSO connector's name, e.g. --auth=okta) or clicks "Sign in with SSO" in the web UI.
2. Redirect to IdP — Mezite redirects the user to the configured identity provider.
3. User authenticates — The user logs in with their corporate credentials at the IdP.
4. IdP responds — The IdP sends an OIDC token or SAML assertion back to Mezite with user attributes (email, groups, etc.).
5. Claims-to-roles mapping — Mezite maps the IdP attributes to Mezite roles and user traits based on the connector configuration.
6. Certificate issued — Mezite's User CA issues a short-lived SSH certificate encoding the user's identity, allowed logins, and expiration. The user is now logged in and can msh ssh into nodes.

user            Mezite proxy           identity provider (IdP)
  |                  |                          |
  |-- msh login ---->|                          |
  |  (--auth=<name>) |                          |
  |                  |-- redirect to IdP ------>|
  |                  |                          |
  |                  |                  user authenticates at IdP
  |                  |                          |
  |                  |<-- OIDC token / SAML ----|
  |                  |    assertion             |
  |                  |                          |
  |<-- SSH cert -----|                          |
  |   (User CA)      |                          |
  |   (mapped roles) |                          |

OIDC Integration (Working)

OpenID Connect (OIDC) is the recommended and currently fully functional SSO protocol. It uses OAuth 2.0 flows to authenticate users and retrieve identity claims.

Step 1: Register Mezite with Your IdP

In your identity provider's admin console, register a new OIDC application:

• Application type: Web application
• Redirect URI: https://mezite.example.com:3080/v1/webapi/oidc/callback
• Scopes: openid, email, profile, groups (if available)

Record the Client ID and Client Secret provided by the IdP.

Step 2: Configure the OIDC Connector

The OIDC connector configuration specifies the IdP connection details and the mapping from IdP claims to Mezite roles.

Connectors are not declared in mezite.yaml; they are stored in the auth backend and managed at runtime via mezctl connectors. The YAML below describes the spec shape for an OIDC connector — see "Configuring Auth Connectors with mezctl" further down for the actual command that creates one.

name: corporate-sso
type: oidc
spec:
  # IdP configuration
  issuer_url: https://accounts.google.com
  client_id: "123456789.apps.googleusercontent.com"
  client_secret: "GOCSPX-abcdefghijklmnop"

  # Redirect URL (must match what you registered with the IdP)
  redirect_url: https://mezite.example.com:3080/v1/webapi/oidc/callback

  # Scopes to request
  scopes:
    - openid
    - email
    - profile

  # Map IdP claims to Mezite roles
  claims_to_roles:
    - claim: groups
      value: "engineering@example.com"
      roles:
        - access
        - ssh-production
    - claim: groups
      value: "platform-team@example.com"
      roles:
        - admin
    # Default role for all authenticated users
    - claim: email
      value: "*@example.com"
      roles:
        - access

Key OIDC Configuration Fields

Step 3: Test the OIDC Connection

# Log in using SSO
msh login --proxy=mezite.example.com:3080 --auth=corporate-sso

# This opens your browser to the IdP login page
# After authenticating, you are redirected back to Mezite

# Verify your identity and roles
msh status
# Cluster:     mezite.example.com
# Proxy:       mezite.example.com:3080
# User:        alice@example.com
# Roles:       access, ssh-production
# Valid until: 2026-03-24 22:15:00 UTC (11h59m remaining)

# You can now SSH into nodes
msh ssh --login=ubuntu web-server-01

SAML 2.0

SAML 2.0 is fully supported with signature verification, encrypted assertions, regex-based role mapping, SP metadata generation, and Single Logout (SLO). Use SAML for identity providers that prefer or require it (Okta, OneLogin, Azure AD in SAML mode).

name: corporate-saml
type: saml
spec:
  # IdP metadata (URL — auto-populates idp_cert, sso_url, idp_issuer)
  idp_metadata_url: https://dev-12345.okta.com/app/abc123/sso/saml/metadata

  # ACS URL
  acs_url: https://mezite.example.com:3080/v1/webapi/saml/acs

  # Entity ID
  entity_id: https://mezite.example.com:3080

  # Map SAML attributes to Mezite roles
  attributes_to_roles:
    - name: groups
      value: "engineering"
      roles:
        - access
        - ssh-production
    - name: groups
      value: "platform-team"
      roles:
        - admin

LDAP / Active Directory

Mezite authenticates users directly against an LDAP directory or Active Directory, mapping LDAP groups to Mezite roles. Group membership is re-resolved on every login so Mezite role assignments track LDAP/AD changes. Connectors are created via mezctl connectors create and secure connections are supported via LDAPS and StartTLS.

name: corporate-ldap
type: ldap
spec:
  # LDAP server
  server: ldaps://ldap.example.com:636

  # Bind credentials
  bind_dn: "cn=mezite,ou=service-accounts,dc=example,dc=com"
  bind_password: "secret"
  start_tls: false

  # User search
  user_search:
    base_dn: "ou=users,dc=example,dc=com"
    filter: "(sAMAccountName={{username}})"
    username_attribute: "sAMAccountName"

  # Group search
  group_search:
    base_dn: "ou=groups,dc=example,dc=com"
    filter: "(member={{user_dn}})"
    group_name_attribute: "cn"

  # Map LDAP groups (by the group_name_attribute, typically cn) to Mezite roles
  groups_to_roles:
    - group: "engineering"
      roles:
        - access
        - ssh-production
    - group: "platform-team"
      roles:
        - admin

GitHub OAuth

GitHub OAuth allows authentication using GitHub accounts, mapping GitHub organization and team membership to Mezite roles. Useful for developer-focused teams that already manage identity through GitHub.

name: github-sso
type: github
spec:
  # GitHub OAuth app credentials
  client_id: "Iv1.abc123def456"
  client_secret: "secret"

  # Redirect URL
  redirect_url: https://mezite.example.com:3080/v1/webapi/github/callback

  # Optional button label shown in the web UI
  display: "Sign in with GitHub"

  # Map GitHub org/team membership to Mezite roles
  teams_to_roles:
    - organization: my-org
      team: engineering
      roles:
        - access
        - ssh-production
    - organization: my-org
      team: platform
      roles:
        - admin

Configuring Auth Connectors with mezctl

Auth connectors can also be managed dynamically using mezctl instead of editing the config file. The CLI is flag-based; pick the flags appropriate for your connector type:

# Create an OIDC connector
mezctl connectors create --name=corporate-sso --type=oidc \
  --issuer-url=https://accounts.google.com \
  --client-id="123456789.apps.googleusercontent.com" \
  --client-secret="GOCSPX-abcdefghijklmnop" \
  --redirect-url="https://mezite.example.com:3080/v1/webapi/oidc/callback" \
  --claims-to-roles="groups:engineering@example.com:access,ssh-production"

# List configured connectors
mezctl connectors list
# NAME           TYPE  ENABLED
# corporate-sso  oidc  true

# Delete a connector
mezctl connectors delete --name=corporate-sso

Local Auth as Fallback

Local password authentication is available alongside any configured SSO connectors, ensuring administrators can still log in if the IdP becomes unreachable. Local accounts must be provisioned explicitly with mezctl users create; an SSO upsert cannot overwrite a local account.

# Log in with local credentials (bypasses SSO)
msh login --proxy=mezite.example.com:3080 --auth=local --user=admin --password=...

Troubleshooting

Redirect loop or callback error

• Verify the redirect URI / ACS URL matches exactly between Mezite config and the IdP.
• Ensure the Mezite proxy's public address and port are correct.
• Check for clock skew between the Mezite server and the IdP.

User has no roles after SSO login

• Check msh status to see which roles were assigned.
• Verify claims_to_roles patterns match the actual claim values from the IdP.
• Review audit events: mezctl audit ls --type=user.login --since=1h

Groups not populated

• For OIDC: ensure the groups scope is requested and the IdP returns group claims.
• For Google: set up the Admin SDK service account for group retrieval.
• For SAML: verify the group attribute statement is configured in the IdP.

Next Steps

• RBAC Configuration — Create roles that use SSO-mapped traits.
• SSH Access — Use SSO-issued certificates for SSH.
• Access Requests — Combine SSO with JIT access workflows.
• Audit Logging — Monitor SSO login events.