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

# SSO Providers

> Configure OAuth 2.0 Single Sign-On providers for automatic user authentication and enrollment.

SSO Providers allow your institution to authenticate users through an external identity provider (e.g., QuickLaunch, Okta, Azure AD) using the OAuth 2.0 Authorization Code flow. Once configured, users visit a dedicated URL (`/sso/{slug}`) and are logged into Pria automatically.

<Note>SSO Providers require the **SSO** admin entitlements (`sso.list`, `sso.add`, `sso.edit`, `sso.delete`). See [Entitlements](/mdx/admin-guide/entitlements) for details.</Note>

***

## How SSO Works

When a user visits the SSO login URL, Pria redirects them to the identity provider for authentication. After the user authenticates, the identity provider sends an authorization code back to Pria, which exchanges it for user information server-side.

```mermaid theme={null}
sequenceDiagram
    participant User as User Browser
    participant Frontend as Pria Frontend
    participant Backend as Pria Backend
    participant IdP as Identity Provider

    User->>Frontend: Visit /sso/{slug}
    Frontend->>Backend: Redirect to /api/auth/sso/{slug}
    Backend->>IdP: 302 Redirect to authorize endpoint
    IdP->>User: Show login page
    User->>IdP: Enter credentials
    IdP->>Frontend: 302 Redirect with authorization code
    Frontend->>Backend: POST /api/auth/sso_callback (code + state)
    Backend->>IdP: Exchange code for access token (server-to-server)
    IdP-->>Backend: Access token
    Backend->>IdP: GET /userinfo with access token
    IdP-->>Backend: User profile (email, name)
    Backend-->>Frontend: JWT + user profile
    Frontend->>User: Logged in, redirect to home
```

<Info>The authorization code is **one-time use** and can only be exchanged for a token using the **client secret**, which only the backend has. The client secret never reaches the browser.</Info>

***

## Managing SSO Providers

Navigate to **Admin > SSO Providers** (`/admin/sso`) to manage your institution's SSO configuration.

### Creating a Provider

<Steps>
  <Step title="Open SSO Providers">
    Navigate to **Admin > SSO Providers** and click **Add SSO Provider**.
  </Step>

  <Step title="Select Institution">
    Choose the institution this SSO provider belongs to. Each institution can have one SSO provider.
  </Step>

  <Step title="Set the Slug">
    Enter a URL-friendly identifier (lowercase letters, numbers, and hyphens only). This becomes the login URL: `https://your-domain.com/sso/{slug}`.
  </Step>

  <Step title="Configure OAuth Endpoints">
    Enter the identity provider's OAuth 2.0 endpoints:

    | Field              | Description                     | Example                                         |
    | ------------------ | ------------------------------- | ----------------------------------------------- |
    | **Client ID**      | OAuth application client ID     | `ilHYXUujI_z1BfNKHpSQ84kDffwa`                  |
    | **Client Secret**  | OAuth application client secret | Stored encrypted, masked in UI                  |
    | **Token Host**     | Base URL for OAuth endpoints    | `https://id.quicklaunch.io:443`                 |
    | **Token Path**     | Path for token exchange         | `/oauth2/token` (default)                       |
    | **Authorize Path** | Path for authorization          | `/oauth2/authorize` (default)                   |
    | **User Info URL**  | Full URL for user info endpoint | `https://id.quicklaunch.io:443/oauth2/userinfo` |
    | **Scope**          | OAuth scope                     | `openid` (default)                              |
  </Step>

  <Step title="Configure Field Mapping">
    Map identity provider user fields to Pria user fields. These defaults match most OpenID Connect providers:

    | Pria Field | Default IdP Field | Description          |
    | ---------- | ----------------- | -------------------- |
    | Email      | `email`           | User's email address |
    | First Name | `given_name`      | User's first name    |
    | Last Name  | `family_name`     | User's last name     |

    <Warning>If your identity provider uses different field names (e.g., `mail` instead of `email`), update the mapping accordingly. Incorrect mapping will prevent user accounts from being created.</Warning>
  </Step>

  <Step title="Enable and Save">
    Toggle **Enabled** to activate the provider, then save. The SSO login URL is immediately active.
  </Step>
</Steps>

### Testing Connectivity

After saving, use the **Test** button to verify the backend can reach the identity provider's token endpoint. This confirms the Token Host URL is correct and accessible.

### Callback URL Registration

You must register the callback URL with your identity provider. The callback URL follows this pattern:

```
https://your-domain.com/sso/{slug}
```

For example, if your domain is `pria.praxislxp.com` and the slug is `my-university`:

```
https://pria.praxislxp.com/sso/my-university
```

<Warning>The callback URL must match **exactly** what is registered with the identity provider. A mismatch will cause an `invalid_callback` error.</Warning>

***

## User Experience

### SSO Login Flow

When a user visits `/sso/{slug}`:

1. If the provider is **enabled**, the user is redirected to the identity provider's login page
2. After authenticating, the user is automatically logged into Pria and enrolled in the associated institution
3. If the user already has an active session, they see options to **Logout** or **Continue**

### Error Handling

| Scenario                | User Sees                                                       |
| ----------------------- | --------------------------------------------------------------- |
| Provider is disabled    | Red error banner: "SSO provider '{slug}' is currently disabled" |
| Provider not found      | Red error banner: "SSO provider '{slug}' not found"             |
| Missing slug (`/sso/`)  | Fallback card with links to Login and Sign Up                   |
| Identity provider error | Error message from the identity provider                        |

***

## Required Entitlements

SSO Provider management requires the following admin entitlements:

| Entitlement  | Allows                         |
| ------------ | ------------------------------ |
| `sso.list`   | View the list of SSO providers |
| `sso.add`    | Create new SSO providers       |
| `sso.edit`   | Modify existing SSO providers  |
| `sso.delete` | Delete SSO providers           |

<Info>These entitlements are managed on the [Entitlements](/mdx/admin-guide/entitlements) page. An admin must have the appropriate SSO entitlements assigned to their institution membership.</Info>

***

## Security

* **Client secrets** are stored in the database and masked in API responses and the admin UI
* The **authorization code** exchange happens server-to-server; the client secret never reaches the browser
* SSO users are automatically enrolled in the institution associated with the provider
* Provider configuration changes take effect immediately (the OAuth client cache is invalidated on save)