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

# OpenID Connect (OIDC)

> Configure Single Sign-On with any OpenID Connect identity provider

OpenID Connect (OIDC) is the recommended protocol for connecting modern identity providers to Modelcode. Any provider that publishes a `/.well-known/openid-configuration` discovery document is compatible.

## 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 OpenID Connect (e.g., GitLab, Azure AD, Auth0, Amazon Cognito, Google Workspace)
* Privileges in your identity provider to create and edit applications and policies

## Step 1: Create an Application in Your Identity Provider

In your identity provider, create a new OIDC application (sometimes called an "OAuth app" or "client"). You will need the following from Modelcode to complete the setup:

| Field            | Description                                                                                                                    |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| **Callback URL** | The redirect URI Modelcode uses to complete authentication. Displayed on the SSO settings page when you select OpenID Connect. |

Configure the application in your identity provider with the following settings:

* **Grant type**: Authorization Code
* **Scopes**: `openid`, `email`, `profile` (at minimum)
* **Redirect URI**: The Callback URL from Modelcode

Once created, your identity provider will give you:

* **Issuer URL** — The base URL of your OIDC provider (e.g., `https://accounts.google.com` or `https://gitlab.com`)
* **Client ID** — The public identifier for the application
* **Client Secret** — The secret used to authenticate the application

## Step 2: Configure OIDC in Modelcode

1. In Modelcode, navigate to **Single Sign-On** in the sidebar
2. Click **Setup SSO** (or **Edit** if updating an existing configuration)
3. Select **OpenID Connect** as the protocol
4. Enter the following:

| Field             | Required          | Description                                                                                                                                                               |
| ----------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Issuer URL**    | Yes               | The base URL of your OIDC provider. Modelcode appends `/.well-known/openid-configuration` automatically — you can paste either the bare issuer or the full discovery URL. |
| **Client ID**     | Yes               | The client identifier from your identity provider.                                                                                                                        |
| **Client Secret** | Yes (first setup) | The client secret from your identity provider. On subsequent edits, this field is masked; leave it unchanged to keep the existing secret.                                 |
| **Scopes**        | No                | Defaults to `openid email profile`. Only change this if your provider requires additional scopes.                                                                         |

5. Click **Verify & Save**

Modelcode fetches the OIDC discovery document and validates that the required endpoints (`authorization_endpoint`, `token_endpoint`, `jwks_uri`) are present. If you entered a new Client ID and Secret, Modelcode also probes the token endpoint to verify the credentials are accepted.

<Note>
  Some identity providers do not support the client-credentials grant used for verification. In that case, the probe result is "inconclusive" and the configuration is saved normally. If the probe detects the credentials are definitively rejected, you'll see a warning — but you can still choose **Save Anyway** if you believe the credentials are correct.
</Note>

## Step 3: 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 OIDC Providers

Any provider with a valid OIDC discovery document works with Modelcode. Common providers include:

* **Okta** — See the [Okta guide](/setup/sso/okta) for step-by-step instructions
* **Amazon Cognito** — See the [Cognito guide](/setup/sso/cognito) for step-by-step instructions
* **Azure AD / Microsoft Entra ID**
* **Auth0**
* **Google Workspace**
* **GitLab**
* **OneLogin**

## Troubleshooting

### "Verification failed" when saving

* Confirm the **Issuer URL** is correct and uses HTTPS
* Verify the URL is publicly reachable (not behind a VPN or firewall)
* Check that the `/.well-known/openid-configuration` endpoint returns a valid JSON document with `issuer`, `authorization_endpoint`, `token_endpoint`, and `jwks_uri`

### Users see "SSO Not Found" on the portal page

* The SSO configuration may have been removed. Check the **Single Sign-On** settings page to confirm it's still active
* Verify the Portal Link URL is correct

### Users can't sign in after SSO is configured

* Ensure the **Callback URL** from Modelcode is registered as a valid redirect URI in your identity provider
* Confirm the **Client ID** and **Client Secret** are correct
* Check that the application in your identity provider is active and not disabled
* Verify the required scopes (`openid`, `email`, `profile`) are allowed for the application
* 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