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

# Single sign-on

> Nash Portal sign-in can be connected to your own identity provider over OpenID Connect or SAML 2.0.

Nash Portal sign-in can be connected to your organization's identity provider (IdP), so your team signs in with the credentials they already have and you keep control of who has access. Nash supports OpenID Connect (OIDC) and SAML 2.0, and configures the connection with you. There is nothing to set up on your own in the Portal.

Single sign-on covers people signing in to the Portal. It does not change how your systems authenticate to the API. That stays [API key based](/reference/authentication), and nothing about your keys changes when you turn SSO on.

## When to use this

Reach for SSO when:

* **You already run an IdP** such as Microsoft Entra ID (formerly Azure AD), Okta, Google Workspace, or Ping, and you want Portal access to follow it.
* **Your security policy requires MFA.** Nash defers to your IdP, so whatever factors you require apply to the Portal too.
* **Offboarding has to be reliable.** Removing someone in your IdP should end their Portal access, without anyone filing a ticket with Nash.
* **You want your groups to decide Nash access.** Your IdP groups can map to Nash roles, so a person's Portal permissions follow their group membership.

If you have a handful of Portal users and no central IdP, or your integration is API-only and nobody signs in to the Portal, SSO buys you little. Skip it.

## What Nash supports

|                             |                                                                                                            |
| --------------------------- | ---------------------------------------------------------------------------------------------------------- |
| Protocols                   | OpenID Connect, SAML 2.0                                                                                   |
| Sign-in directions          | SP-initiated from the Portal; SAML also supports IdP-initiated                                             |
| Multi-factor authentication | Enforced by your IdP; Nash adds no second factor of its own                                                |
| Provisioning                | Just-in-time: the Nash user is created on first successful sign-in                                         |
| Deprovisioning              | Removing a user in your IdP ends Portal access; the Nash user is deactivated, not deleted                  |
| Roles                       | Your organization's default role, or your IdP groups mapped to Nash roles                                  |
| Sign-in routing             | By email domain: users on a domain mapped to your IdP are sent there                                       |
| Identity attribute          | The stable, immutable user identifier from your IdP; for SAML, a persistent identifier or an email address |

## Choose a protocol

Both protocols get you to the same place. They differ sharply in how much work the setup is.

OIDC needs an issuer, a client ID, and a client secret. SAML needs a sign-in endpoint, a signing certificate, and matching assertion configuration on both sides, and its failure modes are quiet ones: a certificate pasted with the wrong boundaries, an audience that doesn't match, a name identifier format that isn't what the other side expects. Each round trip to find one costs both teams an afternoon.

<Tip>
  If your IdP supports OIDC, use OIDC. Choose SAML when your IdP only speaks SAML, when your policy mandates it, or when you need users to start from your IdP dashboard.
</Tip>

## How setup works

Nash configures the connection; you configure an application for Nash in your IdP. To start one, email [tech@usenash.com](mailto:tech@usenash.com) with the protocol you want, which IdP you run, and the email domains your users sign in with.

From there, expect to exchange a small number of values with your Nash contact: the endpoint and identifier details for the application on each side, your IdP's signing certificate or client credentials, and your group-to-role mapping if you want one. Nash provides a secure channel for the certificate and secret handoff; don't send either over email or chat. Once the connection is live, sign in with a single account and confirm the user lands in the right organization with the role you expect before you widen access.

## Users and roles

**First sign-in creates the account.** Nash provisions a user the first time someone signs in successfully through your IdP, so you don't pre-create accounts or send invitations. A new user gets your organization's default Nash role.

**Roles can follow your groups.** Give Nash a mapping from your IdP groups to Nash roles and Nash applies it on every sign-in, so a change in your directory shows up in the Portal the next time that person signs in. Without a mapping, everyone lands on the default role and permissions are managed in the Portal instead. For which roles to map to, see [Roles and access](/reference/roles-and-access).

**Removing access happens in your IdP.** Take someone out of the mapped group or the application in your IdP and they can no longer sign in. Nash deactivates the user rather than deleting them, so the actions they took stay attributed and your history stays intact.

**MFA is your policy, not Nash's.** Nash enforces no second factor of its own and adds nothing on top of what your IdP asks for. Whatever your IdP requires is what Portal sign-in requires.

## Identity attributes

Nash keys a user on the stable, immutable user identifier from your IdP rather than on their email address. That matters at the moment someone changes their name or their email: the identifier doesn't move, so they keep the same Nash user instead of getting a second one.

For SAML, Nash accepts either a persistent identifier or an email address as the name identifier. Prefer the persistent identifier where your IdP offers it. Email addresses change, and when they do, an email-keyed user becomes a new user with none of their history.

## FAQ

<AccordionGroup>
  <Accordion title="Does SSO change how our systems call the Nash API?">
    No. API requests keep using an API key in the `Authorization` header, and your existing keys keep working exactly as they did (see [Authentication](/reference/authentication)). SSO governs people signing in to the Portal, nothing else.
  </Accordion>

  <Accordion title="A script needs to act as a specific user. Can it sign in through SSO?">
    No. SSO is an interactive, browser-based flow. For programmatic access, generate an API key scoped to what the script needs and send it in the request headers. See [API key and Org ID](/reference/generating-api-key-and-org-id).
  </Accordion>

  <Accordion title="Can some of our users sign in with SSO and others with a password?">
    Routing is by email domain. Users whose email is on a domain mapped to your IdP are sent there to sign in; users on other domains are not affected. If you need a mixed arrangement inside one domain, raise it when you start setup, since it changes how the connection is configured.
  </Accordion>

  <Accordion title="Is Microsoft Entra ID supported?">
    Yes. Entra ID (formerly Azure AD) works over either protocol, and OIDC is the faster of the two to stand up. Its group claims can drive Nash roles the same way any other IdP's do.
  </Accordion>

  <Accordion title="Can users start from our IdP dashboard instead of the Portal?">
    With SAML, yes: IdP-initiated sign-in is supported alongside starting from the Portal. OIDC connections start from the Portal.
  </Accordion>

  <Accordion title="Can we try it in Sandbox first?">
    Yes, and it's worth doing. Standing SSO up in [Sandbox](/reference/environments) shakes out role mapping before it affects your production users. Tell your Nash contact which environments you want enabled.
  </Accordion>
</AccordionGroup>

## Related

<CardGroup cols={2}>
  <Card title="Roles and access" icon="user-shield" href="/reference/roles-and-access">
    Which roles to map your groups to, and how to keep configuration and credentials restricted.
  </Card>

  <Card title="Authentication" icon="key" href="/reference/authentication">
    How API requests authenticate, unchanged by SSO.
  </Card>

  <Card title="API key and Org ID" icon="id-card" href="/reference/generating-api-key-and-org-id">
    Create a key in the Portal and find the Org ID your requests need.
  </Card>

  <Card title="Environments" icon="server" href="/reference/environments">
    Sandbox and Production, and what differs between them.
  </Card>
</CardGroup>