Metalogue
Docs

SSO Configuration

Configure SAML 2.0 and OIDC single sign-on for enterprise authentication.

SSO Configuration

Metalogue supports enterprise SSO via SAML 2.0 and OpenID Connect (OIDC).

Supported Providers

SAML 2.0

  • Okta
  • Azure AD
  • OneLogin
  • Ping Identity
  • Generic SAML 2.0

OIDC

  • Okta
  • Azure AD
  • Google Workspace
  • Auth0
  • Generic OIDC

Quick Setup

Okta (SAML)

  1. Create a new SAML app in Okta Admin
  2. Configure:
    • Single Sign On URL: https://api.metalogue.xyz/v1/auth/saml/callback
    • Audience URI: https://api.metalogue.xyz
    • Name ID format: EmailAddress
  3. Copy the IdP metadata URL
  4. Configure in Metalogue:
POST /v1/auth/sso/saml
Content-Type: application/json

{
  "idp_entity_id": "http://www.okta.com/exk...",
  "idp_sso_url": "https://company.okta.com/app/.../sso/saml",
  "idp_certificate": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----",
  "attribute_mapping": {
    "email": "email",
    "name": "displayName",
    "groups": "groups"
  }
}

Azure AD (OIDC)

  1. Register an app in Azure AD
  2. Add redirect URI: https://api.metalogue.xyz/v1/auth/oidc/callback
  3. Create a client secret
  4. Configure in Metalogue:
POST /v1/auth/sso/oidc
Content-Type: application/json

{
  "client_id": "your-client-id",
  "client_secret": "your-client-secret",
  "issuer_url": "https://login.microsoftonline.com/{tenant}/v2.0",
  "scopes": ["openid", "profile", "email"]
}

API Reference

Configure SAML

POST /v1/auth/sso/saml
Content-Type: application/json

{
  "idp_entity_id": "string",
  "idp_sso_url": "string",
  "idp_certificate": "string",
  "attribute_mapping": {
    "email": "string",
    "name": "string",
    "groups": "string"
  }
}

Configure OIDC

POST /v1/auth/sso/oidc
Content-Type: application/json

{
  "client_id": "string",
  "client_secret": "string",
  "issuer_url": "string",
  "scopes": ["openid", "profile", "email"]
}

Get SP Metadata

GET /v1/auth/sso/saml/metadata

Returns XML metadata for SAML Service Provider configuration.

Initiate SSO Login

GET /v1/auth/sso/login?tenant_id={tenant_id}

Redirects to configured IdP.

Get SSO Status

GET /v1/auth/sso/status

Response:

{
  "enabled": true,
  "provider_type": "saml",
  "provider_name": "Okta",
  "last_login": "2026-01-20T01:00:00Z"
}

Attribute Mapping

Map IdP attributes to Metalogue user fields:

Metalogue FieldCommon SAML Attributes
emailemail, NameID, mail
namedisplayName, firstName lastName
groupsgroups, memberOf

Group-to-Role Mapping

Map IdP groups to Metalogue roles:

{
  "group_mapping": {
    "Metalogue-Admins": "admin",
    "Metalogue-Users": "member",
    "Metalogue-Viewers": "viewer"
  }
}

SCIM Integration

For automated user provisioning, see SCIM Provisioning.

Testing SSO

  1. Test Mode: Enable test mode to validate without affecting production
  2. Dry Run: Test SAML response parsing
  3. Debug Logs: Enable verbose SSO logging
POST /v1/auth/sso/test
Content-Type: application/json

{
  "test_mode": true
}

Troubleshooting

Common Issues

IssueSolution
Certificate expiredUpload new IdP certificate
Clock skewEnsure server time is synchronized
Attribute not mappedCheck attribute mapping configuration
Redirect loopVerify callback URL matches exactly

Debug Mode

Enable debug logging:

PATCH /v1/auth/sso/config
Content-Type: application/json

{
  "debug_mode": true
}

Check logs at /v1/audit?action=auth.sso*.

Security Considerations

  1. Use HTTPS - All SSO endpoints require HTTPS
  2. Certificate rotation - Plan for IdP certificate renewal
  3. Session management - Configure appropriate session TTL
  4. MFA enforcement - Enforce MFA at the IdP level

Next Steps