> ## 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.
# Single Sign-On
> Connect your identity provider to Modelcode for centralized authentication
Single Sign-On (SSO) lets your team sign in to Modelcode using your organization's existing identity provider. Instead of managing separate passwords, users authenticate through a provider you already control — such as Okta, GitLab, Amazon Cognito, or any provider that supports OpenID Connect or SAML 2.0.
**To configure SSO, you must be signed in with email and password.** The SSO settings page is not available to admins who signed in with a social provider (GitHub, GitLab, or Microsoft).
## How It Works
Modelcode supports two industry-standard protocols for SSO:
| Protocol | Best For |
| ------------------------- | -------------------------------------------------------------------------------------------- |
| **OpenID Connect (OIDC)** | Modern identity providers with discovery endpoints (GitLab, Auth0, Cognito, Azure AD) |
| **SAML 2.0** | Enterprise identity providers with XML-based federation (Okta, OneLogin, PingFederate, ADFS) |
Both protocols provide the same end-user experience — your team signs in through your identity provider, and Modelcode handles the rest.
**We recommend SAML 2.0 when your identity provider supports it.** SAML is typically quicker to set up — most providers let you configure it with a single metadata URL, without needing to manage client secrets or authorization server policies.
### What Happens When SSO Is Enabled
1. An admin configures the connection between Modelcode and your identity provider
2. Modelcode generates a **Portal Link** — a unique URL for your organization
3. Team members visit the Portal Link and are redirected to your identity provider to authenticate
4. After signing in, they are redirected back to Modelcode with an active session
## The SSO Portal
Every organization with SSO enabled receives a dedicated **Portal Link**. This is the URL your team uses to sign in via your identity provider.
The portal link follows this format:
```
https://morph.modelcode.ai/sso-portal/
```
You can find your portal link on the **Single Sign-On** settings page after configuring your provider. Share this link with your team — it's the entry point for SSO-based sign-in.
Bookmark your Portal Link or add it to your internal wiki so team members can find it easily.
## SSO and Invitations
Users must be invited to your organization before they can sign in with SSO. SSO does not allow self-registration — an admin must send an invitation first. When SSO is enabled, invited users are automatically routed through your identity provider. The invitation email includes a link that takes the user through the SSO flow instead of the standard password-based sign-up.
If a user tries to sign in via the Portal Link without an existing invitation or account, they will see: **"Your organization uses SSO. Please ask your administrator for an invitation to join."**
## Prerequisites
* A Modelcode account with admin access, **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 **OpenID Connect** or **SAML 2.0**
* Privileges in your identity provider to create and edit applications and policies
## Setting Up SSO
To configure SSO, navigate to **Single Sign-On** in the Modelcode sidebar. From there you can:
1. Choose your protocol — **OpenID Connect** or **SAML 2.0**
2. Enter your identity provider details
3. Click **Verify & Save** to validate the connection and activate SSO
Modelcode validates the connection before saving. For OIDC, it fetches the discovery document. For SAML, it parses the metadata or validates the SSO endpoint.
All SSO URLs must use HTTPS. HTTP is not accepted for production configurations.
## Provider Guides
Choose the guide that matches your identity provider:
### By Protocol
* [OpenID Connect (OIDC)](/setup/sso/oidc) — Generic OIDC setup for any compliant provider
* [SAML 2.0](/setup/sso/saml) — Generic SAML setup for any compliant provider
### By Identity Provider
* [Okta](/setup/sso/okta) — Configure Okta with SAML 2.0 or OpenID Connect
* [Amazon Cognito](/setup/sso/cognito) — Configure Amazon Cognito as an OIDC identity provider
## Removing SSO
To remove your SSO configuration, go to the **Single Sign-On** settings page and click **Remove SSO**. This disconnects your identity provider. Existing user accounts are not deleted — users can continue to sign in with any other supported authentication method.
Removing SSO revokes active sessions for users who were signed in via SSO. They will need to sign in again using another method.
## Important Behaviors
### Password Reset Is Disabled for SSO Users
Once a user authenticates through SSO, password reset is no longer available for their account. Since authentication is managed by your identity provider, password changes must be handled there — not in Modelcode.
If a user needs to change their credentials, direct them to your identity provider's self-service password reset flow.
## Troubleshooting
### Portal Errors
These are common errors users may see on the SSO Portal page:
| Error | Cause | Resolution |
| ------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| **"Your organization uses SSO. Please ask your administrator for an invitation to join."** | The user has no account or invitation for this organization. | Admin must send an invitation before the user can sign in via SSO. |
| **"Your email is already associated with a different SSO identity."** | The user's email is linked to a different identity provider account. | Contact your administrator to resolve the identity conflict. |
| **"This account belongs to a different organization."** | The user authenticated with an account that belongs to a different organization. | Use the Portal Link for the correct organization. |
| **"Your identity provider has not verified this email address."** | The identity provider did not mark the user's email as verified. | Verify the email address in your identity provider before retrying. |
| **"Single sign-on failed."** | A general authentication failure occurred. | Try again. If the issue persists, check the SSO configuration and contact support. |
| **"Your identity provider returned an error."** | The identity provider itself failed or rejected the login attempt. | Check your identity provider's logs for details. The user may need to retry or the IdP configuration may need attention. |
### "SSO Not Found" on the Portal Page
The SSO configuration may have been removed or the Portal Link URL is incorrect. Check the **Single Sign-On** settings page to confirm SSO is still active and verify the URL.
