> ## Documentation Index
> Fetch the complete documentation index at: https://docs.modelcode.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# SAML 2.0

> Configure Single Sign-On with any SAML 2.0 identity provider

SAML 2.0 is widely supported by enterprise identity providers. Modelcode acts as the **Service Provider (SP)**, and your identity provider acts as the **Identity Provider (IdP)**.

## Prerequisites

* Admin access to your Modelcode organization, **signed in with email and password** — the SSO settings page is not available to users who signed in with a social provider (GitHub, GitLab, Microsoft)
* An identity provider that supports SAML 2.0 (e.g., Okta, OneLogin, PingFederate, ADFS, Azure AD)
* Privileges in your identity provider to create and edit applications and policies

## Step 1: Get Modelcode's Service Provider Details

Before configuring your identity provider, you need two values from Modelcode:

| Field            | Description                                                                           |
| ---------------- | ------------------------------------------------------------------------------------- |
| **ACS URL**      | The Assertion Consumer Service URL where your identity provider sends SAML responses. |
| **SP Entity ID** | The unique identifier Modelcode uses as a Service Provider.                           |

To get these values:

1. Navigate to **Single Sign-On** in the Modelcode sidebar
2. Click **Setup SSO** and select **SAML 2.0**
3. The **ACS URL** and **SP Entity ID** are displayed at the top of the form — copy them for use in your identity provider

<Note>
  If you don't see these values yet, navigate to the SSO settings page and select SAML 2.0 — they are displayed on the form.
</Note>

## Step 2: Create a SAML Application in Your Identity Provider

In your identity provider, create a new SAML 2.0 application and configure it with:

* **ACS URL** (also called "Reply URL" or "Single Sign-On URL"): Paste the ACS URL from Modelcode
* **Entity ID** (also called "Audience URI" or "Identifier"): Paste the SP Entity ID from Modelcode
* **Name ID Format**: `EmailAddress` (Modelcode matches users by email)
* **Binding**: HTTP-POST (preferred) or HTTP-Redirect

Your identity provider will give you one of:

* **Metadata URL** — A URL that publishes your IdP's SAML metadata XML (recommended)
* **Or** the following individual values:
  * **SSO URL** — The IdP's Single Sign-On endpoint
  * **Entity ID** — The IdP's entity identifier
  * **Signing Certificate** — The X.509 certificate used to sign SAML assertions

## Step 3: Configure SAML in Modelcode

1. In Modelcode, navigate to **Single Sign-On** in the sidebar
2. Click **Setup SSO** (or **Edit** if updating)
3. Select **SAML 2.0** as the protocol
4. Choose your configuration method:

<Tabs>
  <Tab title="Metadata URL (Recommended)">
    Enter the **Metadata URL** from your identity provider. Modelcode automatically extracts the SSO URL, Entity ID, and Signing Certificate from the metadata XML.

    | Field            | Required | Description                                                         |
    | ---------------- | -------- | ------------------------------------------------------------------- |
    | **Metadata URL** | Yes      | The URL where your IdP publishes its SAML metadata. Must use HTTPS. |
  </Tab>

  <Tab title="Manual Configuration">
    Click **Configure manually** to enter the IdP details individually.

    | Field                   | Required          | Description                                                                                                                |
    | ----------------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------- |
    | **SSO URL**             | Yes               | The IdP's Single Sign-On service URL. Must use HTTPS.                                                                      |
    | **Entity ID**           | Yes               | The IdP's entity identifier (also called "Issuer").                                                                        |
    | **Signing Certificate** | Yes (first setup) | The X.509 certificate from your IdP, in PEM format. On subsequent edits, leave unchanged to keep the existing certificate. |
  </Tab>
</Tabs>

5. Click **Verify & Save**

Modelcode validates the configuration by checking that the metadata URL returns valid XML (if using metadata) or that the SSO URL is reachable (if using manual configuration).

## Step 4: Invite Users and Share the Portal Link

Before users can sign in via SSO, they must be invited to Modelcode:

1. Go to the [Members](https://morph.modelcode.ai/user-roles?tab=users) page in Modelcode and invite each user who needs SSO access
2. Copy the **Portal Link** from the Single Sign-On settings page and share it with your team:

```
https://morph.modelcode.ai/sso-portal/<your-organization-id>
```

## Supported SAML Providers

Any provider that supports SAML 2.0 with HTTP-POST or HTTP-Redirect binding works with Modelcode. Common providers include:

* **Okta** — See the [Okta guide](/setup/sso/okta) for step-by-step instructions
* **OneLogin**
* **PingFederate / PingOne**
* **Microsoft ADFS**
* **Azure AD / Microsoft Entra ID** (also supports OIDC)
* **Google Workspace** (also supports OIDC)

## Troubleshooting

### "Verification failed" when saving with a Metadata URL

* Confirm the URL uses HTTPS and is publicly reachable
* Verify the URL returns a valid SAML metadata XML document
* Check that the metadata contains a `SingleSignOnService` element with an HTTP-POST or HTTP-Redirect binding

### "Verification failed" when saving with manual configuration

* Confirm the **SSO URL** uses HTTPS and is reachable
* Verify the **Entity ID** matches what your identity provider reports
* Check that the **Signing Certificate** is a valid X.509 certificate in PEM format

### Users see an error after authenticating with the IdP

* Verify the **ACS URL** in your identity provider exactly matches the value shown in Modelcode
* Confirm the **SP Entity ID** in your identity provider matches the value shown in Modelcode
* Check that the **Name ID Format** is set to `EmailAddress` in your IdP
* Ensure the user's email address in your identity provider matches their Modelcode account email
* Users must be invited to the organization before they can sign in via SSO — SSO does not allow self-registration
* The user's email in the identity provider must be verified — unverified emails are rejected

### SAML assertion signature validation fails

* The signing certificate in Modelcode may be outdated. If your IdP rotated certificates, update the certificate in the Modelcode SSO settings (or re-import via metadata URL)