# Setting Up SSO

This guide walks you through connecting an external identity provider (IdP) to AccessIQ so your users can sign in with their existing corporate credentials.

***

## Before You Begin

* You need the **Owner** or **Admin** role in your tenant.
* You need admin access to the identity provider you are connecting (e.g., Okta admin console, Azure Entra admin center).
* Have your IdP's client ID, client secret, and domain or tenant ID ready.

***

## Supported Identity Providers

AccessIQ supports guided wizard setup for these providers:

| Provider              | Protocol    | SCIM Support |
| --------------------- | ----------- | ------------ |
| Okta                  | OIDC / SAML | Yes          |
| Azure Entra ID        | OIDC / SAML | Yes          |
| Google Cloud Identity | OIDC / SAML | Yes          |
| Auth0                 | OIDC / SAML | Yes          |
| AWS Cognito           | OIDC        | No           |
| Ping Identity         | OIDC        | Yes          |

Additional providers (OneLogin, Keycloak, JumpCloud, ForgeRock, and others) are available through generic OIDC or SAML configuration.

***

## Step 1: Start the IdP Wizard

1. Go to **Identity & SSO > Identity Providers** in the sidebar.
2. Click **Add Provider**.
3. In the provider selector, expand the group that contains your IdP:
   * **Major Cloud Providers** -- Azure Entra ID, AWS Cognito, Google Cloud Identity
   * **Enterprise Identity** -- Okta, Auth0, Ping Identity, and others
4. Click on your provider to select it, then click **Continue**.

The guided wizard opens with steps specific to your chosen provider.

***

## Step 2: Configure the Connection

The wizard walks you through 4--5 steps depending on the provider. Here is what to expect for each major provider:

### Okta

| Step                 | What You Configure                                                              |
| -------------------- | ------------------------------------------------------------------------------- |
| 1. Okta Organization | Your Okta domain (e.g., `your-company.okta.com`) and authorization server       |
| 2. App Credentials   | Client ID and client secret from your Okta application                          |
| 3. Scopes & Groups   | OAuth scopes (openid, profile, email, groups) and group claim mapping           |
| 4. User Sync         | JIT provisioning toggle, default role, default organization, attribute mappings |
| 5. Review & Test     | Summary of all settings and connection test                                     |

### Azure Entra ID

| Step                | What You Configure                                                       |
| ------------------- | ------------------------------------------------------------------------ |
| 1. Azure Tenant     | Your Azure tenant ID and issuer URL                                      |
| 2. App Registration | Client ID and client secret from your Azure app registration             |
| 3. User Sync        | JIT provisioning, default role, default organization, attribute mappings |
| 4. Review & Test    | Summary and connection test                                              |

### Google Cloud Identity

| Step               | What You Configure                                 |
| ------------------ | -------------------------------------------------- |
| 1. Google Project  | Your Google Cloud project details                  |
| 2. Credentials     | OAuth client ID and client secret                  |
| 3. Service Account | Optional service account for directory sync        |
| 4. User Sync       | JIT provisioning, default role, attribute mappings |
| 5. Review & Test   | Summary and connection test                        |

### Auth0

| Step               | What You Configure                                     |
| ------------------ | ------------------------------------------------------ |
| 1. Auth0 Tenant    | Your Auth0 domain (e.g., `your-company.auth0.com`)     |
| 2. App Credentials | Client ID and client secret                            |
| 3. Management API  | Optional management API credentials for directory sync |
| 4. User Sync       | JIT provisioning, default role, attribute mappings     |
| 5. Review & Test   | Summary and connection test                            |

### AWS Cognito

| Step             | What You Configure                                 |
| ---------------- | -------------------------------------------------- |
| 1. User Pool     | AWS region and user pool ID                        |
| 2. Domain        | Your Cognito domain prefix or custom domain        |
| 3. Client        | App client ID and client secret                    |
| 4. User Sync     | JIT provisioning, default role, attribute mappings |
| 5. Review & Test | Summary and connection test                        |

> **Tip:** Each step includes inline help with instructions specific to your provider. Look for the expandable help sections to see exactly where to find each value in your IdP's admin console.

***

## Step 3: Test the Connection

On the final wizard step (Review & Test), click **Test Connection** to verify AccessIQ can communicate with your identity provider.

The test checks:

* The issuer URL is reachable.
* The OIDC discovery document can be fetched.
* The client credentials are valid.

If the test succeeds, you will see a green success message. Click **Save** or **Create Provider** to finish.

### What to verify

* The provider appears in the Identity Providers list with a **Connected** status badge.
* The provider is marked as the **Primary** provider (or set it as primary if this is the first one).

***

## Step 4: Enable JIT (Just-in-Time) Provisioning

JIT provisioning automatically creates user accounts in AccessIQ when someone signs in through the IdP for the first time.

During the wizard's **User Sync** step:

1. Toggle **JIT Provisioning** to on.
2. Select a **Default Role** -- this role is assigned to newly provisioned users (e.g., Member).
3. Select a **Default Organization** -- newly provisioned users are placed in this organization.
4. Configure **Attribute Mappings** to map IdP attributes to AccessIQ fields:
   * `email` -- User's email address
   * `given_name` / `family_name` -- First and last name
   * `groups` -- Group memberships (for automatic role assignment)

If you have already created the provider and need to change these settings:

1. Go to **Identity & SSO > Identity Providers**.
2. Click the edit icon on the provider row.
3. Navigate to the **User Sync** step in the wizard.
4. Update settings and click **Save**.

***

## Step 5: Set the Default Role for SSO Users

The default role determines what access a user gets when they first sign in through SSO.

1. Go to **Access Control > Roles & Permissions** in the sidebar.
2. Review your roles and decide which one is appropriate for new SSO users.
3. Return to the IdP configuration (step 4 above) and select that role as the default.

> **Tip:** Start with a low-privilege role like **Member** or **Viewer** and upgrade users individually or through group-based role mapping.

***

## Step 6: Test the Login Flow

Before rolling out SSO to all users, test the login flow yourself.

1. Open an incognito or private browser window.
2. Navigate to your tenant URL (e.g., `https://your-company.accessiq.app`).
3. On the login page, click the SSO button for your provider (e.g., "Sign in with Okta").
4. Sign in with your IdP credentials.
5. Verify you land on the AccessIQ dashboard with the correct role and organization.

### What to verify

* The login redirects to your IdP and back to AccessIQ without errors.
* Your user record shows the correct name, email, and role.
* If JIT provisioning is on, a new user record is created automatically.
* Check **Security > Login History** to confirm the login event was recorded.

***

## Troubleshooting Common SSO Issues

| Problem                                                    | Likely Cause                  | What to Check                                                                                                                                      |
| ---------------------------------------------------------- | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| "Invalid redirect URI" error                               | Redirect URI mismatch         | In your IdP admin console, make sure the redirect URI matches exactly what AccessIQ expects. Check the wizard's inline help for the correct value. |
| "Client authentication failed"                             | Wrong client secret           | Re-enter the client secret in the IdP wizard. Secrets with special characters may need to be copied carefully.                                     |
| "Discovery document not found"                             | Incorrect issuer URL          | Verify the issuer URL format. For Okta, it should be `https://your-domain.okta.com/oauth2/default`. For Azure, it should include your tenant ID.   |
| User lands on login page again after SSO                   | Session or cookie issue       | Clear cookies, try incognito mode, and check that third-party cookies are not blocked for your domain.                                             |
| User created but wrong role                                | Default role misconfigured    | Go to the IdP wizard's User Sync step and update the default role.                                                                                 |
| User created but no organization                           | Default organization not set  | Go to the IdP wizard's User Sync step and select a default organization.                                                                           |
| "No primary identity provider" warning on Invitations page | No provider marked as primary | Go to Identity & SSO > Identity Providers, find your provider, and mark it as primary.                                                             |
| Login works but groups not synced                          | Group claim not mapped        | In the wizard's Scopes & Groups step, ensure the `groups` scope is requested and the group claim attribute name matches your IdP configuration.    |

***

## Optional: Set Up SCIM Directory Sync

For providers that support SCIM (Okta, Azure Entra, Google, Auth0, Ping), you can set up automatic directory synchronization to keep user accounts in sync.

1. Go to **Identity & SSO > SCIM Provisioning** in the sidebar.
2. Copy the **SCIM Endpoint URL** and **Bearer Token** displayed on the page.
3. In your IdP admin console, configure SCIM provisioning using those values.
4. Enable push operations for user creation, updates, and deactivation.

For more details, see the SCIM Provisioning section in the Identity documentation.

***

## What's Next

* [Onboard your first customer](/accessiq-docs/getting-started/onboarding-a-customer.md) with the SSO connection in place.
* [Investigate security events](/accessiq-docs/getting-started/investigating-security-events.md) to monitor SSO login activity.
* [Configure user mappings](https://github.com/AccessIQ-app/Identia/blob/main/docs/product-guide/identity/user-mappings.md) to customize how IdP attributes map to AccessIQ fields.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://accessiq.gitbook.io/accessiq-docs/getting-started/setting-up-sso.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.