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

# SSO setup

> Connect GetWhys to your identity provider so your team signs in with work credentials.

Single sign-on (SSO) lets your team sign in to GetWhys with their existing work identity — Okta, Microsoft Entra ID (Azure AD), Google Workspace, or another SAML / OIDC provider — instead of managing a separate GetWhys password.

SSO is set up jointly by your IT / IdP admin and GetWhys. It is not a fully self-serve toggle in the app.

## Before you start

You'll need:

* A GetWhys organization where SSO is included in your plan
* An IdP admin who can create a SAML 2.0 or OIDC application (Okta, Entra ID, Google Workspace, OneLogin, Ping, etc.)
* Agreement on which email domains should use SSO (e.g. `acme.com`)

<Note>
  Domain verification in GetWhys is related but separate — see [Domain verification](/account/team-management#domain-verification). Verifying your domain helps control who can join the org; SSO controls how those users authenticate.
</Note>

## Who does what

| Step | Who                | What                                                           |
| ---- | ------------------ | -------------------------------------------------------------- |
| 1    | Your GetWhys admin | Requests SSO and confirms email domains                        |
| 2    | GetWhys            | Provides service provider (SP) details and configures your org |
| 3    | Your IdP admin     | Creates the GetWhys app in your IdP and returns IdP metadata   |
| 4    | Both               | Test sign-in, then roll out to the organization                |

## Step 1: Request SSO for your organization

Reach out via Teams, Slack, Google Chat, or email [team@getwhys.io](mailto:team@getwhys.io) (or your GetWhys contact) and include:

* Your organization name in GetWhys
* Identity provider (e.g. Okta, Microsoft Entra ID, Google Workspace)
* Email domains that should authenticate via SSO
* Whether you prefer **SAML 2.0** or **OIDC** (if your IdP supports both, SAML is the most common enterprise path)
* Whether new users on those domains should be created automatically on first SSO login, or only pre-invited users may sign in — see [Team management](/account/team-management)

## Step 2: Configure your identity provider

GetWhys will send you the service provider values to paste into your IdP app. Typical fields:

| Field (names vary by IdP)                    | What it is                                                |
| -------------------------------------------- | --------------------------------------------------------- |
| **ACS URL** / Reply URL / Single sign-on URL | Where your IdP posts the authentication response          |
| **Entity ID** / Audience URI                 | The GetWhys service provider identifier                   |
| **Metadata URL** (if provided)               | Machine-readable SP metadata for IdPs that support import |
| **Name ID format**                           | Usually email address                                     |

In your IdP, create a new SAML 2.0 (or OIDC) application named something your admins will recognize (e.g. `GetWhys`), enter the SP values GetWhys provided, and assign the users or groups who should have access.

### Attribute mapping

Map at least these attributes from your IdP to GetWhys:

| Attribute      | Required    | Notes                                      |
| -------------- | ----------- | ------------------------------------------ |
| **Email**      | Yes         | Primary identifier for the user in GetWhys |
| **First name** | Recommended | Display name in the product                |
| **Last name**  | Recommended | Display name in the product                |

Exact attribute names depend on your IdP. GetWhys will confirm the expected claim names when you exchange configuration.

## Step 3: Send IdP details back to GetWhys

From your IdP, collect and send to GetWhys:

* IdP metadata XML **or** the IdP SSO URL, Entity ID, and signing certificate
* Confirmed email domains
* Attribute / claim names you configured
* Any IP allowlists or conditional access policies that might block the GetWhys callback

GetWhys completes the configuration on our side and confirms when SSO is ready to test.

## Step 4: Test and roll out

1. Use a test account assigned to the GetWhys app in your IdP.
2. Go to [app.getwhys.io](https://app.getwhys.io) and sign in with that work email (or use the SSO entry point GetWhys provides for your org).
3. Complete the IdP login and confirm you land in the correct GetWhys organization with the right user type.
4. Assign the broader user groups in your IdP and communicate the new sign-in path to your team.

After SSO is live, most users should sign in with work credentials only. Reach out to GetWhys if you want password sign-in disabled for SSO domains.

## Signing in after SSO is enabled

Go to [app.getwhys.io](https://app.getwhys.io), enter your work email, and continue with your organization's identity provider. You should not need a separate GetWhys password for SSO-enabled domains.

If you're new to the organization, you may still need an invitation or domain-based join depending on how your admin configured [Team management](/account/team-management).

## Message for your IdP admin

If you need to brief IT, send something like this:

```
We're enabling SSO for GetWhys (app.getwhys.io) so our GTM team can sign in with company credentials.

We'll need a SAML 2.0 (or OIDC) application in our IdP. GetWhys will provide the ACS URL, Entity ID, and any other SP values. We'll map email (required), first name, and last name, then send back our IdP metadata so they can finish configuration.

Can you create the app and help with the metadata exchange when GetWhys sends the SP details?
```

## Troubleshooting

**Redirected back with an authentication error** — confirm the ACS URL and Entity ID in your IdP match the values GetWhys provided exactly (including `https` and trailing slashes). Confirm the signing certificate GetWhys has is current.

**User can authenticate at the IdP but isn't in GetWhys** — check that their email domain is on the SSO allowlist, that they're assigned to the GetWhys app in the IdP, and that your org allows automatic join or they've been invited — see [Team management](/account/team-management).

**Wrong organization after sign-in** — the email domain may be mapped to a different GetWhys org. Contact GetWhys with the user's email domain.

**SSO button or flow missing** — SSO may not be enabled for your org yet, or you're signing in with a personal email domain. Reach out via Teams, Slack, Google Chat, or email [team@getwhys.io](mailto:team@getwhys.io).

## Related

* [Team management](/account/team-management) — invitations, user types, and domain verification
* [User types](/getting-started/user-types) — what each access level includes
* [Quickstart](/getting-started/quickstart) — first sign-in after your account is ready