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

# Single Sign-On (SSO)

> Let your staff sign in to MtnManager with your own identity provider (Okta, Microsoft Entra, Google Workspace, or any OpenID Connect provider), with automatic user provisioning.

Single Sign-On lets your team sign in to MtnManager using your organization's existing identity provider (IdP) instead of a separate MtnManager password. When SSO is enabled, staff are also **provisioned automatically** the first time they sign in — so you don't have to invite each person one by one. If you'd rather set someone's role *before* they ever sign in, you can still invite them ahead of time — see [Inviting staff ahead of time](#inviting-staff-ahead-of-time).

SSO is configured per resort and uses the **OpenID Connect (OIDC)** standard, so it works with Okta, Microsoft Entra ID, Google Workspace, and most other OIDC providers.

<Note>
  SSO is available on the **Mountain** plan. If you don't see the **SSO** tab under **Settings**, your resort isn't on the Mountain plan.
</Note>

## How it works

<Steps>
  <Step title="A staff member starts sign-in">
    From your resort's MtnManager sign-in page, the user chooses **Sign in with SSO** and is redirected to your identity provider.
  </Step>

  <Step title="They authenticate with your IdP">
    The user signs in with your organization's credentials (and any multi-factor authentication your IdP enforces).
  </Step>

  <Step title="MtnManager creates or links their account">
    On return, MtnManager looks the user up and, if needed, **creates their account automatically** with a role based on their identity-provider groups. The user lands in the dashboard, signed in.
  </Step>
</Steps>

This automatic account creation is called **just-in-time (JIT) provisioning** — see [Automatic user provisioning](#automatic-user-provisioning).

## Before you begin

You'll need:

* A MtnManager role with **permission to manage account settings** (Owner and Administrator roles have this by default).
* Your resort on the **Mountain** plan (see the note above).
* An identity provider that supports **OpenID Connect** with the **authorization code flow**.
* Permission, within your IdP, to register a new application.
* The ability to **add a DNS record** for your email domain — you'll [verify the domain](#step-2-verify-your-email-domain) before SSO can be turned on.

You'll move information between your IdP and MtnManager, so it helps to open both in separate browser tabs.

## Step 1 — Register an application in your identity provider

In your IdP, create a new **OpenID Connect / Web application** using the **authorization code** flow. When prompted for the redirect URI (sometimes called the *callback URL* or *sign-in redirect URI*), use:

```text Redirect URI theme={null}
https://your-resort.mtnmanager.com/api/manage/v1/auth/oidc/callback
```

<Warning>
  Replace `your-resort` with your resort's actual subdomain.
</Warning>

When the application is created, collect these three values — you'll enter them into MtnManager in the next step:

<CardGroup cols={3}>
  <Card title="Issuer URL" icon="link">
    Your IdP's base URL, e.g. `https://your-resort.okta.com`
  </Card>

  <Card title="Client ID" icon="id-card">
    The public identifier for the application you just created.
  </Card>

  <Card title="Client secret" icon="key">
    The confidential secret for the application.
  </Card>
</CardGroup>

### Provider-specific notes

<Tabs>
  <Tab title="Okta">
    1. In the Okta Admin Console, go to **Applications → Create App Integration**.
    2. Choose **OIDC – OpenID Connect** and **Web Application**.
    3. Add the redirect URI above as the **Sign-in redirect URI**.
    4. Assign the people or groups who should have access.
    5. Your **Issuer URL** looks like `https://your-org.okta.com` (or a custom domain).
    6. To let staff launch MtnManager from the Okta tile, also set an **Initiate login URI** — see [Signing in from your identity provider](#signing-in-from-your-identity-provider-idp-initiated).
    7. For [group-to-role mapping](#map-groups-to-roles), add a **groups** claim to the ID token (**Sign On → OpenID Connect ID Token**) — it isn't included by default.
  </Tab>

  <Tab title="Microsoft Entra">
    1. In the Entra admin center, go to **App registrations → New registration**.
    2. Under **Redirect URI**, choose **Web** and add the redirect URI above.
    3. Create a **client secret** under **Certificates & secrets**.
    4. Your **Issuer URL** looks like `https://login.microsoftonline.com/<tenant-id>/v2.0`.
    5. To map roles from groups, add a **groups** claim to the token under **Token configuration**.
  </Tab>

  <Tab title="Google Workspace">
    1. In the Google Cloud console, open **APIs & Services → Credentials**.
    2. Create an **OAuth client ID** of type **Web application**.
    3. Add the redirect URI above under **Authorized redirect URIs**.
    4. Your **Issuer URL** is `https://accounts.google.com`.

    <Warning>
      Google Workspace doesn't include group memberships in the authentication flow, so **group-to-role mapping isn't available with Google**. Every new user receives the [default role](#default-role) — set it to the role appropriate for general staff, and adjust individuals on the Users page after they sign in.
    </Warning>
  </Tab>
</Tabs>

## Step 2 — Verify your email domain

Before you can turn SSO on, MtnManager needs proof that your resort controls the email domain your staff sign in with. This is what lets SSO safely match a person's identity-provider email to their MtnManager account. Without it, another organization's identity provider could assert an email address at your domain and take over an account — so **SSO can't be enabled until at least one domain is verified.** You prove ownership by publishing a DNS record we give you.

<Steps>
  <Step title="Add your domain">
    Go to **Settings → SSO** and find the **Verified Domains** card. Choose **Add a domain** and enter your bare email domain — `your-resort.com`, not a full email address or URL.
  </Step>

  <Step title="Publish the DNS record">
    MtnManager shows a **TXT** record to create with your DNS provider:

    | Field     | Value                                                       |
    | --------- | ----------------------------------------------------------- |
    | **Type**  | `TXT`                                                       |
    | **Host**  | `_mtnmanager-challenge.your-domain.com`                     |
    | **Value** | The exact value shown — use the copy button to avoid typos. |

    Add it at your DNS provider exactly as shown.
  </Step>

  <Step title="Verify">
    Back in MtnManager, choose **Verify**. Once we can see the record, the domain flips to **Verified**. DNS changes can take anywhere from a few minutes to a few hours to propagate, so if the first check doesn't find the record, wait a little and try again.
  </Step>
</Steps>

<Info>
  You can verify **more than one domain**. Add every domain your staff sign in with (for example, if some use `your-resort.com` and others `your-resort.ca`). SSO matches a user as long as their email is on **any** verified domain.
</Info>

<Warning>
  Don't remove a verified domain that SSO relies on. Removing it stops MtnManager from matching sign-ins for email addresses on that domain, so affected staff may be unable to sign in.
</Warning>

## Step 3 — Configure SSO in MtnManager

In the MtnManager dashboard, go to **Settings → SSO** and turn on **Enable SSO**. (The toggle stays disabled until you've [verified a domain](#step-2-verify-your-email-domain).) This reveals the configuration fields:

| Field                  | Description                                                                                                                                                     |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Enable SSO**         | Turns SSO on for your resort and reveals the rest of the settings.                                                                                              |
| **Issuer URL**         | The issuer from Step 1 (e.g. `https://login.example.com`). MtnManager discovers the rest from `{issuer}/.well-known/openid-configuration`.                      |
| **Client ID**          | The client ID from Step 1.                                                                                                                                      |
| **Client secret**      | The client secret from Step 1. Stored encrypted and never shown again. Leave it blank when editing later to keep the existing secret.                           |
| **Default role**       | The role assigned to new users when none of their groups match a role — or **Deny sign-up (no default role)** to block them. See [Default role](#default-role). |
| **Group claim**        | The name of the ID-token claim that lists the user's groups. Defaults to `groups`.                                                                              |
| **Redirect URI**       | Read-only. The exact callback URL to register in your IdP (see [Step 1](#step-1-register-an-application-in-your-identity-provider)). Use the copy button.       |
| **Initiate login URI** | Read-only, optional. The app launch URL for [IdP-initiated sign-in](#signing-in-from-your-identity-provider-idp-initiated). Use the copy button.                |

Click **Save** to store the connection. To turn SSO off later, switch off **Enable SSO** and save, or use **Remove SSO** to delete the configuration entirely.

## Map groups to roles

MtnManager assigns each new SSO user a role automatically based on the groups they belong to in your identity provider. Rather than a single mapping table, you set an **SSO group** on each role you want to map.

To set up mapping, go to the **Roles** page (under **Users → Roles**). When SSO is enabled, each role shows an **SSO Group** column:

<Steps>
  <Step title="Open a role's SSO group">
    Find the role you want to map and choose **Set SSO Group**.
  </Step>

  <Step title="Enter the group identifier">
    In **Group identifier**, enter the exact group value your identity provider sends. The value depends on your IdP:

    * **Okta and most other providers** — the **group name** (for example `ski-patrol`).
    * **Microsoft Entra** — the group's **object ID** (like `a1b2c3d4-...`), not its name.
    * **Google Workspace** — not supported; Google doesn't send groups, so mapping has no effect.

    Leave it blank to remove the binding.
  </Step>

  <Step title="Save">
    Repeat for each role you want IdP groups to map to.
  </Step>
</Steps>

When a user signs in, MtnManager reads the groups from their token (using the **group claim** you configured) and assigns the role whose **SSO group** matches one of those groups. If no group matches — or your IdP doesn't send groups — the user gets the **default role**.

<Info>
  Group-to-role mapping only applies when a user account is **first created**. Changing a user's groups later won't automatically change their MtnManager role. You can adjust an existing user's role at any time on the Users page.
</Info>

### Default role

The **default role** (set on the SSO settings screen) is assigned to any new SSO user whose groups don't match a role's SSO group. We recommend choosing the **least-privileged** role appropriate for general staff (for example Lift Operator), then granting higher roles via group bindings.

Alternatively, choose **Deny sign-up (no default role)** to block sign-in for anyone whose groups don't match a mapped role. Use this when you want only explicitly-mapped groups to be able to sign in.

## Automatic user provisioning

The first time someone signs in via SSO, MtnManager resolves their account in this order:

<Steps>
  <Step title="Existing SSO user">
    If they've signed in via SSO before, they're matched to their existing account.
  </Step>

  <Step title="Existing email match">
    If a MtnManager user already exists with the same email address in your resort — including someone you [invited ahead of time](#inviting-staff-ahead-of-time) — that account is **linked** to their identity-provider identity and activated. Their existing role is kept (group mapping doesn't override it).
  </Step>

  <Step title="New user (just-in-time provisioning)">
    Otherwise, a new active user is created automatically, with a role from your [group mapping](#map-groups-to-roles) (or the [default role](#default-role)). If the default role is set to **Deny sign-up** and no group matches, the user is not provisioned.
  </Step>
</Steps>

## Inviting staff ahead of time

Automatic provisioning is convenient, but it only assigns a role *when someone first signs in*. If you'd rather decide a person's role in advance — for example, to give an incoming manager elevated access from their very first sign-in instead of relying on group mapping — you can invite them before they join.

<Steps>
  <Step title="Invite the user">
    On the **Users** page, choose **Add user**, enter their name and email, and assign the role(s) you want them to have. Use the email address they'll sign in with at your identity provider, on one of your [verified domains](#step-2-verify-your-email-domain).
  </Step>

  <Step title="They sign in with SSO">
    The invited person signs in through your identity provider as normal — there's no password to set.
  </Step>

  <Step title="MtnManager links and activates them">
    On that first sign-in, MtnManager links the invitation to their identity-provider identity, keeps the roles you assigned, and activates their account.
  </Step>
</Steps>

<Info>
  Roles you assign at invite time take precedence over [group mapping](#map-groups-to-roles): the user keeps the roles from their invitation rather than being assigned a role from their groups. You can change them later on the Users page.
</Info>

<Note>
  The email address on the invitation must be on a [verified domain](#step-2-verify-your-email-domain) or sign-in won't link to the invited account. This is the same protection that applies to automatic provisioning.
</Note>

## Signing in with SSO

Once SSO is enabled, your resort's sign-in page shows a **Sign in with SSO** button beneath the email/password form. Staff click it to be taken to your identity provider and back, signed in. The button only appears on your resort's own subdomain.

## Signing in from your identity provider (IdP-initiated)

As well as starting from MtnManager's sign-in page, your staff can launch MtnManager **directly from your identity provider** — for example by clicking the MtnManager tile on their Okta dashboard or Microsoft MyApps page. This is called **IdP-initiated sign-in**.

It uses the same secure OpenID Connect flow under the hood: clicking the tile sends the user to MtnManager, which immediately bounces them to your IdP to authenticate and then back, signed in. No separate setup is required beyond the steps below.

To enable it, set the **Initiate login URI** (sometimes called the *app launch URL* or *initiate login URL*) in your IdP application. You can copy the exact value from the **Initiate login URI** field on the SSO settings screen (**Settings → SSO**); it looks like:

```text Initiate login URI theme={null}
https://your-resort.mtnmanager.com/api/manage/v1/auth/oidc/initiate
```

<Warning>
  Replace `your-resort` with your resort's actual subdomain.
</Warning>

<Tabs>
  <Tab title="Okta">
    1. Open your MtnManager app integration, then **General → Settings → Edit**.
    2. Under **Login**, set **Login initiated by** to **Either Okta or App**.
    3. Set **Initiate login URI** to the URL above.
    4. Under **Application visibility**, tick **Display application icon to users** so the tile appears on users' Okta dashboards.
  </Tab>

  <Tab title="Microsoft Entra">
    1. Open your app registration, then **Branding & properties**.
    2. Set the **Home page URL** to the URL above.
    3. The app will then appear on users' [MyApps](https://myapps.microsoft.com) page and can be launched from there.
  </Tab>

  <Tab title="Google Workspace">
    Google's app launcher links to a URL you choose when you publish the app to your organization. Set that launch URL to the **Initiate login URI** above.
  </Tab>
</Tabs>

## Need help?

Contact [support@mtnmanager.com](mailto:support@mtnmanager.com) and we'll help you get SSO set up for your resort.