MountainGoat · Single Sign-On & Provisioning

Microsoft Entra ID SSO & Provisioning: MountainGoat Configuration Guide

For Microsoft Entra administrators connecting a Microsoft 365 tenant to a MountainGoat instance for sign-in, and optionally for automatic user provisioning.

1.Overview and security model

MountainGoat supports Microsoft Entra ID as an OIDC single sign-on provider, a peer of Sign in with Okta. When SSO is enabled, your users see a Sign in with Microsoft button on the MountainGoat login page and can also launch MountainGoat from their My Apps portal.

• Entra authenticates; MountainGoat authorizes. Entra verifies who the user is and returns a signed ID token. A user's actual access is always determined by their MountainGoat role, assigned directly or through app-role mapping (see section 6).
• Single tenant, pinned. The token's issuer is resolved from your tenant's discovery document and its tenant claim must equal the configured Tenant ID. The multi-tenant aliases common, organizations, and consumers are refused when the configuration is saved.
• Stable identity. MountainGoat stores the user's directory object id (objectId / oid) as the account's identity, so the identity survives app re-registration. This is also why SCIM provisioning must send that same object id as externalId (see section 9).
• Secrets are write-only. The client secret is stored encrypted, never displayed back, and the browser receives only configured or not-configured status.
• Outage-tolerant, never locked out. Microsoft's discovery document is cached for 24 hours with stale-if-error fallback, so a Microsoft outage degrades to a clear error page for SSO users while local login keeps working. Email and password sign-in coexists with SSO unless you deliberately switch Require SSO on.
• The Goat copilot stays out. It cannot configure SSO, read SSO secrets, or change authentication behavior.

Supported: SP-initiated SSO, the My Apps tile, Just-In-Time account creation, app-role mapping, and optional SCIM 2.0 provisioning. Not supported: Single Logout (SLO), multi-tenant app registrations, and force authentication.

2.Decide first: SSO only, or SSO + provisioning?

SSO alone is a complete setup. Steps 1–9 give your users Sign in with Microsoft, app-role-driven MountainGoat roles, and Require SSO if you want it. You create one Entra app, you need no Entra ID license tier, and you are done. Most instances stop here; accounts are created by invitation from the Users tab, exactly as they are without SSO.

SCIM provisioning is optional, and it is what makes offboarding a push from Entra rather than a refusal at next login. Add it when you want Entra to create, update, and deactivate MountainGoat accounts for you. It requires Entra ID P1 and a second Entra app.

The two apps are tied together by the user's directory object id, which is identical in both. That is why the externalId mapping in step 16a is mandatory. Assignments are per app: app roles on the sign-in app drive MountainGoat roles, and users and groups on the provisioning app decide who gets provisioned. Assign the same people to both.

3.Prerequisites

• Entra administrator role: Application Administrator, Cloud Application Administrator, or Global Administrator (required to register apps and assign users).
• Your MountainGoat subdomain. Each production MountainGoat instance is reachable at https://{app.subdomain}.mountaingoat.ai. Throughout this guide, {app.subdomain} is a placeholder for your subdomain label. Replace it everywhere it appears with your own label (for example acme, producing acme.mountaingoat.ai).
• A MountainGoat administrator account to enter the credentials in the MountainGoat Admin UI.
• For SCIM provisioning only: Entra ID P1 or above on your tenant (see section 2).

4.Set up the sign-in app in Entra

Sign in to the Microsoft Entra admin center at https://entra.microsoft.com (or https://portal.azure.com → Microsoft Entra ID), then:

1. App registrations → New registration, single tenant (Accounts in this organizational directory only). From the app's Overview page, note the Directory (tenant) ID and Application (client) ID.
2. Redirect URI (Web): paste the value shown in the MountainGoat SSO panel; the panel pre-fills it and offers a Copy button. It has this shape:
   • Redirect URI (Web) https://{app.subdomain}.mountaingoat.ai/auth/entra/callback
   • SP-initiated login URL (open this to start SSO) https://{app.subdomain}.mountaingoat.ai/auth/entra/login
3. Certificates & secrets → New client secret. Copy the secret value now; it is entered once in MountainGoat and never shown again. Note the expiry date too.
4. App roles: create roles named for MountainGoat (for example MG-Admin, MG-Manager, MG-Editor, MG-Viewer), then assign users or groups to those roles on the app's Enterprise application entry. App-role names arrive in the token's roles claim, the recommended source, readable in the mappings JSON (see section 6).
   • Fallback for organizations that do not use app roles: Token configuration → add the groups claim, set MountainGoat's Group Claim to groups, and map group GUIDs instead of names.
   • On a free tenant, assign users to app roles; assigning groups to app roles needs Entra ID P1.
5. Optional (My Apps tile): set the Enterprise application's Home page URL to https://{app.subdomain}.mountaingoat.ai/auth/entra/login. The tile launch is plain SP-initiated sign-in; no separate initiate-login URI exists for Entra.

5.Enter the credentials in MountainGoat

Sign in to your MountainGoat instance as an administrator, click Settings under the user profile, then select the Admin tab → API & Credentials → SSO Credentials → Entra ID Credentials.

6. Paste the Tenant ID, Client ID, and Client Secret; confirm the pre-filled Redirect URI; choose the Group Claim (roles is the default); map roles under Group/Role Mappings; set the Default Role; set the JIT Mode: strict if you are doing SSO only, mapped if you are going on to set up provisioning (see section 7 for why); set Enabled to Yes; Save.
7. Test connection. Green means your tenant's discovery document and signing keys are reachable and the issuer resolved. The result is kept as a last-tested chip in the panel.
8. Sign out and verify Sign in with Microsoft appears on the login page. Sign in with a test user, then confirm the mapped role and the sign-in entry in the SSO Status panel's audit trail.
9. Only after a successful Entra sign-in by a second full admin: optionally switch Require SSO on (the shared switch in the SSO Policy block; it is saved with either provider's Save button). The panel refuses the switch while no SSO provider is available, and a startup self-check protects against locking the instance out either way.

Doing SSO only? You are done. Accounts stay invitation-managed from the Users tab, and nothing in section 9 applies to you.

6.User roles and access

MountainGoat has five access roles: No access, View only, PO edit, Manager, and Full admin.

Recommended: app roles

App roles (step 4) are the recommended way to carry role information from Entra: they are assigned per application, their names arrive in the roles claim, and the Group/Role Mappings stay readable (MG-Admin → full_admin, and so on). Keep MountainGoat's Group Claim on roles.

Fallback: the groups claim

If your organization does not use app roles, add the groups claim under the app registration's Token configuration, set MountainGoat's Group Claim to groups, and map group GUIDs instead of names.

No mappings at all

Mappings are optional. Without them, users receive the Default Role and your MountainGoat administrator assigns roles by hand under Settings → Admin → Users. Entra confirms who the person is, and MountainGoat controls what they can do.

7.Provisioning modes (JIT)

The JIT Mode field decides what happens when someone signs in through Entra who has no MountainGoat account yet:

strict is the recommended steady state either way; it keeps account creation a deliberate act. Which value you start on depends on which path you are taking:

• SSO only: use strict from the start. Your people already have MountainGoat accounts (you invited them from the Users tab), so strict simply links each one by verified email on their first Microsoft sign-in. Nothing to loosen, and it is the safest posture. Anyone new gets invited first, then signs in.
• SSO + provisioning: start on mapped, tighten to strict at step 22. Between the moment SSO goes live and the moment provisioning finishes its first cycle, the people Entra is about to create are not in MountainGoat yet. Under strict every one of those sign-ins is refused with unknown_user_strict_mode, which reads as a broken SSO setup when it is really an empty user table. mapped lets your assigned users in on their mapped role while you work through section 9; once Entra has run a full cycle and the Users tab shows the accounts it created, switch to strict. From then on, someone removed from the Entra app cannot re-create themselves by signing in.

Changing the mode is a Save on the same form and takes effect on the next sign-in.

8.Sign-in email and allowed domains

The sign-in email is resolved from the token by precedence: email, then preferred_username (when it contains @), then upn (when it contains @). Which claim was used is recorded in the audit trail per login, so a tenant whose UPNs are not real mailboxes is diagnosable. A token with no resolvable email is refused, never linked to a guessed identity.

This precedence is also why the SCIM userName mapping in step 16 matters: provisioning must write the same address sign-in will resolve, or the same person arrives twice.

Allowed Email Domains (optional): enter one or more domains separated by commas, for example acme.com, partner.com, to limit sign-in to those domains. Everyone else is denied with email_domain_not_allowed. The restriction applies to the resolved email value. Leave the field blank to allow any domain your Entra assignment permits.

9.SCIM provisioning (optional)

Add this section when you want Entra's provisioning service to create, update, and deactivate MountainGoat users automatically over SCIM 2.0, chiefly so that offboarding is a push from Entra rather than a refusal at next login. It is a platform capability on every MountainGoat instance, no extra module required, but it requires Entra ID P1 (or above) on your tenant: Microsoft gates automatic provisioning behind it.

Before you start, re-read section 2. Steps 12–13 create the second Entra app it describes.

In MountainGoat: generate the token

10. In the SCIM Provisioning section of the same SSO Credentials pane, switch Provisioning Enabled to Yes and click Save SCIM Config. This switch is also the kill switch: turning it off refuses every SCIM request immediately, even with a valid token.
11. Enter a token label (for example Entra prod) and click Generate Token. The token is shown exactly once; copy it now. It is stored hashed and can never be displayed again. Copy the read-only Tenant URL too:
    • Tenant URL https://{app.subdomain}.mountaingoat.ai/scim/v2?aadOptscim062020
    A blank label is refused. Refusals show in the message line at the top of the SCIM Provisioning section, above the Provisioning Enabled switch; if a click seems to do nothing, look up there rather than at the button.

In Entra: create the provisioning app

12. Enterprise applications → New application → Create your own application. Name it something you will recognize beside the sign-in app (for example MountainGoat Provisioning), choose Integrate any other application you don't find in the gallery (Non-gallery), and Create. This second app is required: automatic provisioning is not offered on the enterprise application behind your sign-in registration (see section 2).
13. Open the new app → Provisioning → Get started → set Provisioning Mode to Automatic.

In Entra: connect it

14. Under Admin Credentials, paste the MountainGoat Tenant URL into Tenant URL and the generated token into Secret Token, then click Test Connection. Green means Entra reached your instance and the token was accepted. A red result here is almost always the token (copied with trailing whitespace, already rotated, or revoked) or the Provisioning Enabled switch being off; either refusal is recorded in the panel's Provisioning Activity readout.
15. Save the Admin Credentials. The Mappings section appears only after a successful save.

In Entra: fix the mappings (do not skip this)

16. Open Mappings → Provision Microsoft Entra ID Users. Entra ships this app with a default mapping set MountainGoat does not accept as-is. Two edits are required.

    16a: Change externalId to objectId. This is mandatory. The default source for externalId on a non-gallery app is mailNickname. Click that row and change the source attribute to objectId.

    If you leave externalId on mailNickname, identity correlation breaks. MountainGoat stores each Entra user's directory object id as the account's identity when they sign in. Provisioning looks a user up by externalId before deciding whether to create them. With mailNickname there, that lookup never matches an account that has already signed in, so Entra tries to create someone who already exists, MountainGoat refuses the duplicate email with a 409 uniqueness error, and the cycle reports errors on exactly the people who were working fine. mailNickname is also editable in the directory, so it can change out from under the link; objectId never does.

    16b: Delete every mapping row that is not on this list. MountainGoat implements the attribute subset it actually stores. Entra sends changed attributes as explicit SCIM paths, and a path outside this list is refused with 400 invalidPath; one such row makes every update fail even though the initial create succeeded. Keep exactly these seven rows:

    Keep this SCIM attribute	Source it to
    userName	userPrincipalName (the default), but see the note below
    active	Not([IsSoftDeleted]) (the default)
    displayName	displayName (the default)
    name.givenName	givenName (the default)
    name.familyName	surname (the default)
    externalId	objectId (changed in 16a)
    emails[type eq "work"].value	mail (the default)

    Delete all the rest. The rows Entra adds by default that MountainGoat refuses include name.formatted, preferredLanguage, title, every addresses[...] row (streetAddress, locality, region, postalCode, country, formatted) and every phoneNumbers[...] row (work, mobile, fax). Anything under the enterprise-user extension schema (department, manager, employeeNumber) goes too. None of them map to a MountainGoat field, so deleting them loses nothing; job title in particular is a MountainGoat field you set in MountainGoat, not one provisioning fills in.

    On userName: MountainGoat resolves the sign-in email as email → preferred_username → upn, and for most tenants the email claim comes from the user's mail attribute. If your users' UPNs are their real mailboxes, Entra's userPrincipalName default is fine; leave it. If they are not, change the source to the expression Coalesce([mail], [userPrincipalName]) so provisioning writes the address sign-in will resolve. Getting this wrong makes the same person arrive as two accounts.

17. Leave Match users based on as it ships (userName, matching precedence 1). Save the mappings.

In Entra: assign, test, and start

18. Users and groups → Add user/group. Assign the same people you assigned to app roles on the sign-in app. Assignment on this app controls who gets provisioned; assignment on the sign-in app controls what role they get.
19. Provision on demand for one test user. Read the result screen: it names each attribute it sent and the response it got. A green create means MountainGoat accepted it.
20. In MountainGoat's Users tab, confirm the test user appears with the Entra badge, the Provisioned chip, and the Default Role from the Entra credentials form. Check the panel's Provisioning Activity readout too.

    First and Last name blank? That is not a MountainGoat fault. Entra sends whatever givenName and surname hold, and plenty of directories leave those empty even when the display name looks fine, so such a person reads as nameless in the Users table. Populate First name and Last name on the user in Entra and provision on demand again. A name typed into MountainGoat instead can be overwritten the next time Entra syncs that user.

21. Start provisioning. The first cycle takes up to about 40 minutes. Afterwards, verify the create, update, and deactivate counts in the Provisioning Activity readout.
22. Now tighten JIT to strict on the Entra ID Credentials form, per section 7.
23. Deprovision test: disable the test user in Entra, provision on demand, and confirm the MountainGoat account deactivates and any open session ends on its next request.

Behavior to know

• Provisioned users receive the Default Role configured in the Entra ID Credentials form; one role knob covers JIT and SCIM alike. They carry no local password and sign in with Microsoft.
• Deactivation is immediate. active: false (and SCIM DELETE, which deactivates; MountainGoat never hard-deletes over SCIM) revokes every live session. The last active full administrator can never be deactivated via SCIM.
• Groups are stored and acknowledged, not role-driving. Group sync succeeds and memberships are recorded, but roles keep coming from app-role claims at sign-in. Group membership never changes anyone's MountainGoat role.
• Token hygiene. Rotate replaces a token atomically (the old one stops working the moment the new one exists); revoke kills one immediately; the panel lists each token's label, creator, and last-used time, never the token itself.
• Both arrival orders work, with one cosmetic lag. Someone provisioned first links automatically on their first Microsoft sign-in. Someone who signed in before provisioning started is found by their object id and updated in place, no duplicate, but their Provisioned chip appears only once Entra has actually written to them, which is the next sync cycle or a Provision on demand. An Entra badge with no Provisioned chip during that window is expected, not a failure. It is also why step 16a matters: the object-id lookup is what finds them.
• Unknown attributes on a create are ignored; unknown paths on an update are refused. A create carrying attributes MountainGoat does not store still succeeds, which is why a bad mapping set can pass step 19 and then fail on every later update. Step 16b is what prevents that.

10.Troubleshooting

Every failed Entra sign-in shows a short error code on a clear error page and writes the same code to the audit trail. The SSO Status panel shows the last error reason with its time; it never shows secrets, tokens, raw claims, or signing keys.

Sign-in errors

Provisioning errors

Entra reports these on the provisioning app's Provisioning logs; the matching refusal also lands in MountainGoat's Provisioning Activity readout.

11.Requirements

• Entra SSO needs no Entra ID license tier. A free tenant covers everything through step 9 (assigning groups to app roles is the one piece that needs P1; assigning users does not).
• SCIM provisioning requires Entra ID P1 (or above) on your tenant; Microsoft gates automatic provisioning behind it.
• Network: your instance needs outbound access to login.microsoftonline.com for SSO. SCIM is inbound-only: Microsoft's provisioning service calls your instance, and MountainGoat calls nothing in your tenant for it.
• HTTPS: the Redirect URI and SCIM Tenant URL derive from your instance's public https address. Managed instances at {app.subdomain}.mountaingoat.ai already satisfy this.

12.Support

For help configuring Microsoft Entra SSO or SCIM provisioning for MountainGoat, contact:

help@mountaingoat.ai