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

# Authentication and access

> Connect your identity provider, require it for sign-in, enforce MFA there, and grant Mount Thor permissions

Mount Thor signs people in through your organization's identity provider over
SAML or OpenID Connect, including Google Workspace, Okta and Microsoft Entra
ID. Multi-factor authentication is your provider's: for Google Workspace that
means security keys such as YubiKeys, authenticator apps or text-message codes,
whichever your Workspace policy allows. Permissions are separate from sign-in.
A role assignment in Mount Thor decides what a signed-in person can do.

Use this page to connect your provider, verify your domains, test a pilot
sign-in, require the provider for your organization, enforce MFA, and give
people and automation the access they need.

## What is available

| Capability | Availability | Where it is configured |
| - | - | - |
| Enterprise SSO | SAML and OIDC, including Google Workspace, Okta and Microsoft Entra ID | The setup portal Mount Thor invites your administrator to |
| Google sign-in and email codes | On, for people who are not routed to an SSO connection | The Mount Thor sign-in page |
| Hardware-key MFA, including YubiKey | Through your identity provider | Your provider's MFA policy |
| Authenticator app and text-message MFA | Through your identity provider. Mount Thor has no MFA of its own | Your provider's MFA policy |
| Passwords and passkeys on Mount Thor itself | Off | Not configurable |
| Directory sync and SCIM | Unsupported: membership comes from invitations and roles | `mthr members`, `mthr iam` |
| Permissions and automation | Roles for members and service accounts, credentials for automation | `mthr iam`, `mthr service-accounts` |

> [!NOTE]
>
> **Sign-in, MFA and permissions are three separate settings.** Connecting a
> provider decides how people prove who they are. The provider's policy decides
> which factors they use. A Mount Thor role decides what they can do. None of the
> three sets the others.

## Before you begin

* A Mount Thor tenant and an **active tenant owner** who can invite members and
  grant roles.
* An administrator for your identity provider. The Google Workspace procedure
  needs a super administrator.
* Access to the DNS records of every email domain you will verify.
* The email address of your identity administrator, and the list of domains
  and external guests in the rollout.
* A pilot user who already holds a Mount Thor membership and a role. See
  [Invite teammates and assign permissions](#invite-teammates-and-assign-permissions).
* Security keys, or another factor your MFA policy will require, for the
  people in the rollout.

### Install the CLI and identify your tenant

```bash theme={null}
curl -fsSL https://get.mountthor.com/install.sh | sh
```

Run the PATH export the installer prints, then sign in with your tenant-owner
account:

```bash theme={null}
mthr version
mthr login
mthr whoami
```

Copy the **Account ID** that `mthr whoami` prints. Every command on this page
applies to the signed-in tenant. See [Quickstart](https://docs.mountthor.com/quickstart.md) and
[Account](https://docs.mountthor.com/platform/account.md).

## Connect your identity provider

### 1. Request the setup invitation

Email [hello@mountthor.com](mailto:hello@mountthor.com) with:

```text theme={null}
Subject: Configure SSO for [company]

Mount Thor tenant name:
Account ID (from mthr whoami):
IT administrator email:
Identity provider:
Company email domains, including additional domains:
Required MFA method:
External guest email addresses or domains:
```

Mount Thor sends your identity administrator an email with your organization's
setup link. The link opens a guided setup hosted by WorkOS, the sign-in service
Mount Thor uses, with a step for domain verification and a step for single
sign-on. The link is valid for 30 days or until the setup is complete. To
replace an expired link, reply on the same email thread.

### 2. Verify your email domains

1. Open **Domain Verification** in the setup portal and enter your company
   email domain.
2. Copy the TXT record name and value the portal shows.
3. Add that record at your DNS provider.
4. Return to the setup portal and complete verification.
5. Repeat for every additional domain in the rollout.

**Check:** each domain shows as verified in the setup portal. Sign-ins from a
verified domain are routed to your connection.

### 3. Configure your provider

Open **Single Sign-On** in the setup portal and select your provider. The
portal shows the values your provider needs and walks through the provider's
own steps. Use the values it generates for your organization.

| Provider | Reference |
| - | - |
| Google Workspace SAML | The walkthrough below, and the [WorkOS Google SAML guide](https://workos.com/docs/integrations/google-saml) |
| Okta SAML | [WorkOS Okta SAML guide](https://workos.com/docs/integrations/okta-saml) |
| Microsoft Entra ID SAML | [WorkOS Entra ID SAML guide](https://workos.com/docs/integrations/entra-id-saml) |
| OpenID Connect | [WorkOS OIDC guide](https://workos.com/docs/integrations/oidc) |
| Other providers | Select the provider in the portal. The [WorkOS integration guides](https://workos.com/docs/integrations) cover the provider-specific fields |

#### Google Workspace SAML

Select **Google Workspace SAML** in the setup portal and keep the **ACS URL**
and **SP Entity ID** it shows at hand.

1. In [Google Admin](https://admin.google.com/), open **Apps → Web and mobile
   apps → Add app → Add custom SAML app**.
2. Enter **Mount Thor** as the application name.
3. On **Google Identity Provider details**, download the metadata XML.
4. Enter the service-provider settings:

| Google field | Value |
| - | - |
| ACS URL | The ACS URL from the setup portal |
| Entity ID | The SP Entity ID from the setup portal |
| Name ID format | `UNSPECIFIED` |
| Name ID | **Basic Information → Primary email** |

5. Add these attribute mappings, then finish creating the application:

| Google Directory attribute | App attribute |
| - | - |
| Primary email | `email` |
| First name | `firstName` |
| Last name | `lastName` |

6. Return to the setup portal and upload the Google metadata XML.

### 4. Assign pilot users and test the connection

1. Assign the pilot user or group to the application in your provider. In
   Google Admin, open the application's **User access**, select the
   organizational unit or group, turn access **On**, and save.
2. Run the portal's **Test sign-in** with an assigned pilot account.
3. Complete a real sign-in at
   [portal.mountthor.com](https://portal.mountthor.com/sign-in) with that
   user's invited Mount Thor email.

**Check:** the test completes and the user reaches the intended tenant with
the permissions already assigned to them. Google documents application-access
changes taking up to 24 hours to propagate.

> [!NOTE]
>
> **Use the same email address.** The provider's primary email and the Mount
> Thor membership email must match. A working connection grants no Mount Thor
> permissions on its own. Invite the member and assign a role as described
> below.

## Require SSO and MFA

### Require your provider for your organization

After the pilot sign-in succeeds, reply on the setup thread with the tested
user and the verified domains, and ask Mount Thor to require SSO for your
company domains and for guest members of your organization. Mount Thor sets the
organization's sign-in policy and confirms it with a fresh sign-in test. Repeat
a fresh sign-in with a company user afterwards.

With the policy on, a sign-in from a verified domain can use only your
connection. People outside your organization can still use Google sign-in and
email codes.

> [!WARNING]
>
> **Existing sessions are not ended by the policy change.** A person who signed
> in by another method before the change keeps that session until it expires or
> the member is deactivated. To end it sooner, deactivate and re-invite the
> member.

### Require YubiKeys or other hardware security keys

For SSO users, MFA is configured in the identity provider. The sign-in flow
delegates the MFA challenge to it, and Mount Thor doesn't add a second prompt.

In Google Workspace:

1. In Google Admin, open **Security → Authentication → 2-step verification**
   and select the rollout's organizational unit or group.
2. Turn on **Allow users to turn on 2-Step Verification**.
3. Have each user open **Google Account → Security → How you sign in to Google
   → 2-Step Verification**, turn it on, and enrol their security key.
4. Once everyone is enrolled, set **Enforcement** to **On** and **Methods** to
   **Only security key**, then save.

Google's **Only security key** method includes passkeys. To allow physical
keys only, also open **Security → Authentication → Passwordless → Passkeys
restriction**, select **Allow passkeys on hardware security keys only**, and
save. Enrolling a passkey by itself turns 2-Step Verification on for nobody.

References: [security-key enrollment](https://support.google.com/accounts/answer/6103523),
[2-Step Verification enforcement](https://knowledge.workspace.google.com/admin/security/deploy-2-step-verification),
[hardware-key restriction](https://knowledge.workspace.google.com/admin/users/allow-users-to-skip-passwords-at-sign-in).

### Allow authenticator apps or text messages instead

In **Google Admin → Security → Authentication → 2-step verification**, choose
the methods your organization permits:

| Method | Administrator setting | User enrollment |
| - | - | - |
| Authenticator app | **Methods** set to **Any**, or to **Any except verification codes via text, phone call** | In Google Account's **2-Step Verification** settings, **Set up authenticator** |
| Text-message code | **Methods** set to **Any** | In Google Account's **2-Step Verification** settings, enrol a phone number |

Google verifies these codes, and Mount Thor relies on that verification
rather than running a code method of its own.

### Sessions and repeated MFA prompts

Your provider's own session decides how often a person is challenged again.
Google's **Allow user to trust the device** setting, and an existing Google
session, both apply. A new visit to Mount Thor by itself does not ask for a
fresh key touch.

A Mount Thor session lasts up to 12 hours. `mthr whoami` shows when the CLI
session expires. `mthr logout` asks Mount Thor to revoke the session and
removes the stored credential from the machine. The identity-provider session
is separate: end it there to sign out everywhere.

## Invite teammates and assign permissions

Run these commands as an **active tenant owner**. Copy `MEMBER_ID`, `ROLE_ID`
and `BINDING_ID` from the command output. Replace `CHANGE_REFERENCE` with your
organization's access-request ticket.

### Invite a teammate

```bash theme={null}
mthr members invite user@example.com
mthr members ls
```

The recipient opens the invitation and signs in. With a connection in place,
that sign-in goes through your provider. To inspect, resend or cancel:

```bash theme={null}
mthr members get MEMBER_ID
mthr members resend INVITATION_ID
mthr members cancel INVITATION_ID
```

An invitation alone doesn't grant tenant access. Assign a role next.

### Assign a role

```bash theme={null}
mthr iam roles ls
mthr iam roles get ROLE_ID

mthr iam bindings grant --member-id MEMBER_ID --role-id ROLE_ID \
  --reason "Approved project access" \
  --ticket CHANGE_REFERENCE

mthr iam bindings ls --member-id MEMBER_ID --json
```

**Check:** the binding and the required actions appear in the result. Grant
and revoke need a reason and a ticket for the audit record. Custom roles and
the action catalog are on [Roles and bindings](https://docs.mountthor.com/platform/roles-and-bindings.md)
and [Actions](https://docs.mountthor.com/platform/actions.md).

### Verify portal and CLI access

Have the member sign in at
[portal.mountthor.com](https://portal.mountthor.com/sign-in), then on their own
machine:

```bash theme={null}
mthr login
mthr whoami
```

On a machine without a browser, `mthr login --no-browser` prints a URL and a
code to use on another device. The owner can read back the member's effective
access with `mthr iam bindings ls --member-id MEMBER_ID --json`.

## Authenticate automation

Automation uses a service account with its own role bindings and credentials.
The full lifecycle, including rotation and the 90-day credential lifetime, is
on [Service accounts](https://docs.mountthor.com/platform/service-accounts.md).

```bash theme={null}
mthr service-accounts create
mthr iam bindings grant --service-account-id SERVICE_ACCOUNT_ID --role-id ROLE_ID \
  --reason "Approved automation access" \
  --ticket CHANGE_REFERENCE
mthr service-accounts credentials create SERVICE_ACCOUNT_ID
```

> [!WARNING]
>
> **Save the credential when it is created.** Its secret is shown once. Store it
> in the automation's secret manager and expose it to the job as
> `MOUNTTHOR_SA_CREDENTIAL`.

A service account signs in with its credential, never through your identity
provider, so your SSO and MFA policies do not apply to it. Its access is
exactly the roles you grant it.

## Remove access

### Remove a member

```bash theme={null}
mthr members deactivate MEMBER_ID
mthr iam bindings ls --member-id MEMBER_ID --json
mthr iam bindings revoke BINDING_ID \
  --reason "Access removed" \
  --ticket CHANGE_REFERENCE
```

Deactivation ends the member's Mount Thor session and stops new sign-ins.
Remove the person's application assignment in your provider as well, so the
provider stops issuing them a sign-in for Mount Thor. Removing them from the
provider alone leaves the membership in place until it is deactivated.

### Recover from a lost security key

Your Google administrator opens **Directory → Users → \[user] → Security →
2-step verification → Get Backup Verification Codes** and recovers the account
under your policy. The lost key is then removed or replaced. In
security-key-only mode, recovery codes are issued by the administrator. See
[Google account recovery](https://knowledge.workspace.google.com/admin/security/recover-an-account-protected-by-2-step-verification).

## Troubleshooting

| Problem | What to check |
| - | - |
| Setup invitation expired | Reply on the original thread to [hello@mountthor.com](mailto:hello@mountthor.com) and ask for a replacement |
| Domain is not verified | Compare the DNS TXT record name and value with the setup portal, then repeat verification |
| SAML sign-in fails | Compare the ACS URL, Entity ID, Name ID and attribute mappings with the provider configuration, and confirm the user is assigned to the application |
| Google application assignment just changed | Google documents propagation taking up to 24 hours. Confirm the right organizational unit or group was updated |
| A member is sent to a password or code prompt instead of your provider | The email domain is not verified yet, or the connection is not active |
| Sign-in succeeds but access is denied | Confirm the membership email and tenant, then inspect `mthr iam bindings ls --member-id MEMBER_ID --json` for the required action |
| A user is not asked for a security key again | Review Google's session and trusted-device policy. A Mount Thor visit by itself does not require a new key touch |

Write to [hello@mountthor.com](mailto:hello@mountthor.com) with the tenant
name, the affected email, the failing step and the error text. For permission
errors, include the owner's binding readback. Never include credentials,
recovery codes or setup links.

## Related documentation

* [Team members](https://docs.mountthor.com/platform/members.md)
* [Roles and bindings](https://docs.mountthor.com/platform/roles-and-bindings.md)
* [Actions](https://docs.mountthor.com/platform/actions.md)
* [Account](https://docs.mountthor.com/platform/account.md)
* [Service accounts](https://docs.mountthor.com/platform/service-accounts.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.