SAML SSO

MITRITY supports enterprise SAML 2.0 single sign-on (SSO), allowing your team to authenticate using your existing identity provider (IdP). SAML SSO provides centralized authentication, automatic user provisioning, and compliance with enterprise identity policies.

Overview

When SAML SSO is configured for your tenant:

1. Users navigate to the MITRITY login page.
2. MITRITY detects the user's email domain and redirects them to your IdP.
3. The user authenticates with the IdP (using your organization's MFA, password policies, etc.).
4. The IdP sends a SAML assertion back to MITRITY.
5. MITRITY validates the assertion and creates a session.
6. If the user does not exist in MITRITY (first login), JIT provisioning creates their account automatically.

User ──login──► MITRITY ──redirect──► IdP (Okta/Azure AD/Google)
                                         │
                                    authenticate
                                         │
User ◄────session────── MITRITY ◄──assertion──┘

Supported Identity Providers

MITRITY supports any SAML 2.0-compliant identity provider. The most common are:

IdP	Status	Notes
Okta	Fully supported	Pre-built SAML app available in Okta catalog
Azure AD (Entra ID)	Fully supported	Enterprise Application setup
Google Workspace	Fully supported	Custom SAML app setup
OneLogin	Supported	Standard SAML 2.0 configuration
PingIdentity	Supported	Standard SAML 2.0 configuration
Auth0	Supported	Standard SAML 2.0 configuration
JumpCloud	Supported	Standard SAML 2.0 configuration

Prerequisites

Before configuring SAML SSO, ensure:

• You have Owner role in your MITRITY tenant.
• You have administrative access to your identity provider.
• You know the email domain that will use SSO (e.g., company.com).
• Your subscription plan supports SAML SSO (Pro or Enterprise plan).

MITRITY SAML Configuration

Service Provider (SP) Details

When configuring your IdP, you need the following MITRITY details:

Field	Value
Entity ID (Audience)	https://api.mitrity.com/saml/{tenant_id}
ACS URL (Reply URL)	https://api.mitrity.com/saml/{tenant_id}/acs
SLO URL (optional)	https://api.mitrity.com/saml/{tenant_id}/slo
Name ID Format	urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress

Replace {tenant_id} with your actual tenant ID (found in Settings > General > Tenant ID).

Required SAML Attributes

MITRITY expects the following attributes in the SAML assertion:

Attribute	Required	Description
email	Yes	User's email address (used as unique identifier)
firstName or givenName	Yes	User's first name
lastName or surname	Yes	User's last name
groups (optional)	No	Group memberships for role mapping

Setup by Identity Provider

Okta Setup

Step 1: Create a SAML Application

1. Log in to your Okta admin dashboard.
2. Navigate to Applications > Applications > Create App Integration.
3. Select SAML 2.0 and click Next.
4. Enter the application name: MITRITY.
5. Upload the MITRITY logo (optional).
6. Click Next.

Step 2: Configure SAML Settings

Field	Value
Single sign-on URL	https://api.mitrity.com/saml/{tenant_id}/acs
Audience URI (SP Entity ID)	https://api.mitrity.com/saml/{tenant_id}
Name ID format	EmailAddress
Application username	Email

Step 3: Configure Attribute Statements

Name	Value
email	user.email
firstName	user.firstName
lastName	user.lastName

Step 4: Download IdP Metadata

1. Click Next and complete the Okta setup.
2. Navigate to the Sign On tab of your new SAML app.
3. Under SAML Signing Certificates, click Actions > View IdP metadata.
4. Copy the metadata URL or download the XML.

Step 5: Assign Users

1. Navigate to the Assignments tab.
2. Assign users or groups that should have access to MITRITY.

Azure AD (Entra ID) Setup

Step 1: Create an Enterprise Application

1. Log in to the Azure portal.
2. Navigate to Azure Active Directory > Enterprise Applications > New Application.
3. Click Create your own application.
4. Enter the name: MITRITY.
5. Select Integrate any other application you don't find in the gallery (Non-gallery).
6. Click Create.

Step 2: Configure Single Sign-On

1. Navigate to Single sign-on > SAML.
2. Click Edit on Basic SAML Configuration.

Field	Value
Identifier (Entity ID)	https://api.mitrity.com/saml/{tenant_id}
Reply URL (ACS URL)	https://api.mitrity.com/saml/{tenant_id}/acs
Sign on URL	https://mitrity.com/login

Step 3: Configure Attributes and Claims

1. Click Edit on Attributes & Claims.
2. Add the following claims:

Claim Name	Source Attribute
email	user.mail
firstName	user.givenname
lastName	user.surname

Step 4: Download Certificate and Metadata

1. Under SAML Certificates, download the Certificate (Base64).
2. Copy the Login URL and Azure AD Identifier from the SAML configuration section.

Step 5: Assign Users and Groups

1. Navigate to Users and groups.
2. Add the users or groups that should have access to MITRITY.

Google Workspace Setup

Step 1: Create a Custom SAML App

1. Log in to the Google Admin console.
2. Navigate to Apps > Web and mobile apps > Add App > Add custom SAML app.
3. Enter the name: MITRITY.

Step 2: Download IdP Information

1. On the Google Identity Provider details page, download the certificate and copy the SSO URL and Entity ID.

Step 3: Configure Service Provider Details

Field	Value
ACS URL	https://api.mitrity.com/saml/{tenant_id}/acs
Entity ID	https://api.mitrity.com/saml/{tenant_id}
Name ID format	EMAIL
Name ID	Basic Information > Primary email

Step 4: Configure Attribute Mapping

Google Directory Attribute	App Attribute
Primary email	email
First name	firstName
Last name	lastName

Step 5: Enable the App

1. Click Finish to create the app.
2. Click on the app name and set Service status to ON for everyone (or for specific organizational units).

Configuring MITRITY

After configuring your IdP, enter the IdP details in MITRITY.

Via the Dashboard

1. Navigate to Settings > Security > SAML SSO.
2. Click Configure SSO.
3. Enter the IdP details:

Field	Description	Example
Entity ID	The IdP's entity ID (also called Issuer)	https://accounts.google.com/o/saml2?idpid=abc123
SSO URL	The IdP's single sign-on URL	https://accounts.google.com/o/saml2/idp?idpid=abc123
Certificate	The IdP's signing certificate (PEM format)	-----BEGIN CERTIFICATE-----\nMIIC...
Email Domain	The email domain that should use this SSO configuration	company.com

4. Click Save Configuration.
5. Click Test SSO to verify the configuration.

Via the API

curl -X PUT https://api.mitrity.com/api/v1/tenant/saml \
  -H "Authorization: Bearer mk_live_your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "entity_id": "https://accounts.google.com/o/saml2?idpid=abc123",
    "sso_url": "https://accounts.google.com/o/saml2/idp?idpid=abc123",
    "certificate": "-----BEGIN CERTIFICATE-----\nMIIC...\n-----END CERTIFICATE-----",
    "email_domain": "company.com",
    "jit_provisioning": true,
    "default_role": "member",
    "default_access_scope": "scoped",
    "default_environment_ids": ["env_development"]
  }'

Response:

{
  "data": {
    "enabled": true,
    "entity_id": "https://accounts.google.com/o/saml2?idpid=abc123",
    "sso_url": "https://accounts.google.com/o/saml2/idp?idpid=abc123",
    "email_domain": "company.com",
    "jit_provisioning": true,
    "default_role": "member",
    "default_access_scope": "scoped",
    "default_environment_ids": ["env_development"],
    "configured_at": "2026-03-01T10:00:00Z",
    "last_tested_at": null,
    "test_status": null
  },
  "meta": {
    "request_id": "req_saml001",
    "timestamp": "2026-03-01T10:00:00Z"
  }
}

Configuration Fields

Field	Type	Required	Description
enabled	boolean	Yes	Enable or disable SAML SSO
entity_id	string	Yes	The IdP's entity ID / issuer URL
sso_url	string	Yes	The IdP's SSO login URL
certificate	string	Yes	The IdP's X.509 signing certificate in PEM format
email_domain	string	Yes	The email domain to route to this IdP
jit_provisioning	boolean	No	Enable Just-In-Time user provisioning (default: true)
default_role	enum	No	Role assigned to JIT-provisioned users (default: member)
default_access_scope	enum	No	Access scope for JIT-provisioned users (default: scoped)
default_environment_ids	array	No	Environments granted to JIT-provisioned users

JIT Provisioning

Just-In-Time (JIT) provisioning automatically creates a MITRITY user account when a user authenticates via SAML for the first time. This eliminates the need to manually invite every user.

How JIT Works

1. User authenticates with the IdP.
2. IdP sends a SAML assertion to MITRITY.
3. MITRITY validates the assertion.
4. If the user does not exist in MITRITY, a new account is created with:
   • Email from the SAML assertion
   • Name from the SAML assertion
   • Role from default_role setting
   • Access scope from default_access_scope setting
   • Environment access from default_environment_ids setting
5. The user is logged in and can immediately use MITRITY.

JIT Provisioning Settings

Setting	Default	Description
jit_provisioning	true	Enable automatic account creation on first SAML login
default_role	member	Role assigned to new JIT users
default_access_scope	scoped	Access scope for new JIT users
default_environment_ids	[]	Environments granted to new JIT users (empty = no environment access until an Owner assigns it)

Disabling JIT

If JIT provisioning is disabled, users must be manually invited via the dashboard or API before they can log in with SAML SSO. The IdP authenticates them, but MITRITY rejects the login if no matching user account exists.

Auth Provider Detection

When a user enters their email on the MITRITY login page, the system checks the email domain:

1. If the domain matches a configured SAML SSO domain, the user is redirected to the IdP.
2. If no SAML configuration exists for the domain, the user sees the standard login form (email/password or Google SSO).

This allows tenants with mixed authentication — some users via SAML, others via email/password or Google SSO.

Testing SSO Configuration

Via the Dashboard

1. Navigate to Settings > Security > SAML SSO.
2. Click Test SSO.
3. A new window opens and redirects to your IdP.
4. Authenticate with the IdP.
5. If successful, the window shows a success message with the parsed SAML attributes.
6. If failed, the window shows the error details.

Troubleshooting Common Issues

Issue	Cause	Resolution
"Invalid assertion signature"	Certificate mismatch	Re-download the IdP certificate and update in MITRITY
"Audience mismatch"	Entity ID in IdP does not match MITRITY's expected value	Verify the Entity ID matches https://api.mitrity.com/saml/{tenant_id}
"ACS URL mismatch"	Reply URL in IdP does not match MITRITY's expected value	Verify the ACS URL matches https://api.mitrity.com/saml/{tenant_id}/acs
"Name ID not found"	IdP not sending email as Name ID	Configure Name ID format as emailAddress in IdP
"User not found"	JIT provisioning is disabled and user has no account	Enable JIT or manually invite the user
"Certificate expired"	The IdP's signing certificate has expired	Renew the certificate in the IdP and update in MITRITY

MFA with SAML SSO

When SAML SSO is configured, MFA is enforced at the IdP level. MITRITY trusts the IdP's authentication decision, including any MFA the IdP enforces. MITRITY does not add a second MFA challenge after SAML authentication.

Important: Ensure your IdP enforces MFA. MITRITY requires MFA for all authentication methods. If your IdP does not enforce MFA, configure it to do so before enabling SAML SSO.

Multiple Domains

MITRITY supports SAML SSO for multiple email domains. Each domain can use a different IdP:

# Configure SSO for company.com (Okta)
curl -X PUT https://api.mitrity.com/api/v1/tenant/saml \
  -H "Authorization: Bearer mk_live_your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "entity_id": "https://company.okta.com/app/abc123",
    "sso_url": "https://company.okta.com/app/abc123/sso/saml",
    "certificate": "...",
    "email_domain": "company.com"
  }'

# Configure SSO for subsidiary.com (Azure AD)
curl -X PUT https://api.mitrity.com/api/v1/tenant/saml \
  -H "Authorization: Bearer mk_live_your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "entity_id": "https://login.microsoftonline.com/tenant-id",
    "sso_url": "https://login.microsoftonline.com/tenant-id/saml2",
    "certificate": "...",
    "email_domain": "subsidiary.com"
  }'

Best Practices

Test Before Enforcing

Configure and test SAML SSO before making it the only authentication method. Ensure at least one Owner account can log in via SAML before disabling other methods.

Keep a Break-Glass Account

Maintain at least one Owner account with email/password authentication as a backup in case SAML SSO fails (IdP outage, certificate expiration). This account should use a separate email domain not covered by SAML.

Enable JIT Provisioning

JIT provisioning reduces administrative burden and ensures users can access MITRITY immediately after IdP authentication. Set a restrictive default_role (Member or Viewer) and let Owners assign higher roles as needed.

Monitor Certificate Expiration

IdP certificates typically expire every 1-3 years. Set a calendar reminder to renew the certificate before it expires. Expired certificates cause immediate SSO failures for all users.

Enforce MFA at the IdP

Since MITRITY trusts the IdP's authentication, ensure your IdP enforces MFA for all users. MITRITY's MFA requirement is satisfied by IdP-enforced MFA.

Related Documentation

• RBAC — Role-based access control and user management
• Environments — Environment access for JIT-provisioned users
• API Keys — Programmatic access (not SSO-dependent)
• Billing — SAML SSO requires Pro or Enterprise plan