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.

User initiates login — The user runs msh login --auth=sso or clicks "Sign in with SSO" in the web UI.
Redirect to IdP — Mezite redirects the user to the configured identity provider.
User authenticates — The user logs in with their corporate credentials at the IdP.
IdP responds — The IdP sends an OIDC token or SAML assertion back to Mezite with user attributes (email, groups, etc.).
Claims-to-roles mapping — Mezite maps the IdP attributes to Mezite roles and user traits based on the connector configuration.
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.

SSO to certificate flow text

user            Mezite proxy           identity provider (IdP)
  |                  |                          |
  |-- msh login ---->|                          |
  |  (--auth=sso)    |                          |
  |                  |-- 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.

OIDC connector configuration yaml

# In mezhub's mezite.yaml
auth:
  connectors:
    - type: oidc
      name: corporate-sso
      display_name: "Sign in with Corporate SSO"

      # 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 user traits
      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

Field	Description
`issuer_url`	The OIDC issuer URL of your IdP (used for discovery)
`client_id`	OAuth 2.0 client ID registered with the IdP
`client_secret`	OAuth 2.0 client secret
`redirect_url`	Callback URL that must match the IdP registration
`claims_to_roles`	Maps IdP claims (groups, email, etc.) to Mezite roles

Step 3: Test the OIDC Connection

Test OIDC login bash

# 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
# User:    alice@example.com
# Roles:   access, ssh-production
# Valid:   12h (expires 2026-03-24T22:15:00Z)
# Auth:    corporate-sso (OIDC)

# 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).

SAML connector configuration yaml

auth:
  connectors:
    - type: saml
      name: corporate-saml
      display_name: "Sign in with Okta"

      # IdP metadata (URL or inline XML)
      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/corporate-saml

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

      # Map SAML attributes to Mezite roles
      attributes_to_roles:
        - attribute: groups
          value: "engineering"
          roles:
            - access
            - ssh-production
        - attribute: 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. Features include connector creation via mezctl, web-based login, automatic group synchronization, TOTP MFA enforcement, and secure connections via LDAPS and StartTLS.

LDAP connector configuration yaml

auth:
  connectors:
    - type: ldap
      name: corporate-ldap
      display_name: "Sign in with Active Directory"

      # LDAP server
      url: ldaps://ldap.example.com:636

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

      # User search
      user_base_dn: "ou=users,dc=example,dc=com"
      user_filter: "(sAMAccountName={{.Username}})"

      # Group search
      group_base_dn: "ou=groups,dc=example,dc=com"
      group_filter: "(member={{.UserDN}})"

      # Map LDAP groups to Mezite roles
      groups_to_roles:
        - group: "cn=engineering,ou=groups,dc=example,dc=com"
          roles:
            - access
            - ssh-production
        - group: "cn=platform-team,ou=groups,dc=example,dc=com"
          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.

GitHub OAuth connector configuration yaml

auth:
  connectors:
    - type: github
      name: github-sso
      display_name: "Sign in with GitHub"

      # GitHub OAuth app credentials
      client_id: "Iv1.abc123def456"
      client_secret: "secret"

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

      # 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:

Auth connector management bash

# Create a connector from a YAML file
mezctl connectors create oidc-connector.yaml

# List configured connectors
mezctl connectors ls
# NAME              TYPE    DISPLAY NAME
# corporate-sso     oidc    Sign in with Corporate SSO
# local             local   Local Account

# View a connector's configuration
mezctl connectors show corporate-sso

# Update a connector
mezctl connectors update oidc-connector.yaml

# Delete a connector
mezctl connectors rm corporate-sso

Local Auth as Fallback

Local password authentication is always available as a fallback, even when SSO is configured. This ensures administrators can always access the cluster if the IdP is unavailable.

Local auth fallback bash

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

# You can disable local auth for non-admin users if desired:
# In mezhub's mezite.yaml:
# auth:
#   local:
#     enabled: true
#     # Only allow local auth for users with the admin role
#     allowed_roles: [admin]

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 --last=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.