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

# SAML SSO Setup

> Use Invoca's self-service setup wizard to connect your identity provider (Okta, Microsoft Entra ID, Google Workspace, Auth0, ADFS, PingFederate, and other standard enterprise IdPs) so your organization can log in to Invoca through SAML SSO.

If your organization uses an identity provider (IdP) to log in to your apps, you can use that same service to log in to Invoca. Once enabled, anyone in your organization logging in to Invoca is directed to sign in through your SSO provider instead.

Using the self-service setup wizard, you can configure a SAML 2.0 or OIDC connection with your company's IdP. Supported providers include Okta, Microsoft Entra ID (Azure AD), Google Workspace, Auth0, ADFS, PingFederate, and other standard enterprise IdPs.

<Note>
  **SAML SSO is a different feature from Affiliate/Advertiser SSO**

  SAML SSO (this article) is a different feature from the similarly-named SSO for Affiliates and Advertisers, which allows performance marketers to more easily share Invoca access with Advertisers and Publishers on their network. For help with that feature instead, see [How to Share Invoca Data with Affiliates and Advertisers Using Single Sign-On (SSO)](/s/article/share-invoca-data-affiliates-advertisers-sso).
</Note>

## Before you begin

* **Invoca role:** You must be a Network Super User (the highest permission level) to access SSO settings.
* **IdP admin access:** You need administrator access to your company's Identity Provider to create a new enterprise application.
* **Time allocation:** The secure setup link Invoca generates expires after 8 hours. Plan to complete the wizard in one session.

## Setting up SSO

1. **Generate the setup link.** Log in to Invoca and go to **Settings > Users**. Click the kebab menu (three vertical dots) in the top right and select **SSO Settings**. Enter a friendly name for your connection (for your own internal reference) and click **Begin SSO Setup**. This opens the Setup Wizard in a new browser tab. The link expires in 8 hours.
2. **Select your IdP.** Follow the wizard's steps and choose your IdP, or select Custom SAML or Custom OIDC.
3. **Configure SAML settings.** In Step 2 of the wizard, copy your unique connection endpoints — the **Single Sign-On URL** (also called ACS URL or Reply URL) and the **Service Provider Entity ID** (also called Audience URI or Entity ID) — and paste them into the corresponding fields in your new IdP application.
4. **Map user attributes.** Configure your IdP to send the required user data to Invoca. Attribute names must exactly match the Attribute Mappings Reference table below. Save your IdP application once mapped. If you're using Okta and need to map an attribute that isn't in Okta's base profile — such as a phone number — see [How to Add and Map Custom Attributes in Okta for Configuring Required SSO/SAML Parameters](/s/article/How-to-Add-and-Map-Custom-Attributes-in-Okta-for-Configuring-Required-SSO-SAML-Parameters).
5. **Connect your IdP to Invoca.** Return to the wizard's Step 3 (Configure Connection) and provide your IdP's details:
   * **Automatic setup (recommended):** Paste your IdP's metadata URL. For Okta: Sign On > View SAML setup instructions > Identity Provider Metadata URL. For Entra ID: SAML Signing Certificate > App Federation Metadata URL. For Google Workspace: download the metadata file and host it at a secure URL.
   * **Manual setup:** If a metadata URL isn't available, use the Manual tab to enter your Sign-In URL, Sign-Out URL, and X.509 certificate directly.
6. **Assign access and test.** In your IdP, assign the Invoca application to test users or groups. In the wizard's Step 5, use the built-in test feature to perform a full login round-trip. A green success indicator confirms the connection works. Complete the wizard and click **Enable**.
7. **Enforce SSO logins.** Return to the SSO Settings pane and confirm your connection status reads **Ready**. Set your SSO Enforcement mode (Optional or Mandatory) and click **Save**.

## Attribute Mappings Reference

Your IdP must pass these attributes to Invoca during authentication. Attribute names are case-sensitive and must match exactly.

| Friendly Name | Attribute Name | Required? | Notes |
| :- | :- | :- | :- |
| First Name | `first_name` | Required | User's given name |
| Last Name | `last_name` | Required | User's family name |
| Email Address | `email` | Required | Can be passed via NameID or as a separate attribute |
| Invoca Memberships | `invoca_memberships` | Optional | Multi-valued list defining organization access and roles. Format: `Type:Id:Role[:filters]`, e.g. `Network:*:Member` or `Advertiser:12345:Manager` |
| Timezone | `time_zone` | Optional | Must be a valid Rails/IANA timezone name, e.g. `America/Los_Angeles` |
| Contact Phone | `contact_phone_number` | Optional | If omitted, the account is created without a phone number |
| Licenses | `licenses` | Optional | Comma-separated list (`marketing`, `contact_center`). If omitted, users receive the network default |

## FAQs and troubleshooting

**"Certificate mismatch" error.** The X.509 certificate in your IdP's SAML application doesn't match what Invoca has on file — usually because the IdP rotated its signing certificate, or the wrong certificate was uploaded during setup. In Invoca's SSO Settings, click **Edit SSO Configuration**, then re-enter your IdP metadata URL or manually upload the new certificate.

**"Missing attributes" error.** One or more required attributes are absent from the SAML assertion. Review the Attribute Mappings table above and confirm `first_name`, `last_name`, and `email` are configured in your IdP with the correct, lowercase attribute names.

**403 error during login.** A 403 error when logging in (rather than during setup) usually means either a required attribute is missing from the SAML response or the response's signature is invalid — see [403 Error: Required Attributes](/s/article/403-error-saml-sso-required-attributes) and [403 Error: Invalid Signature](/s/article/403-error-saml-sso-invalid-signature) for the specific symptoms and fix for each.

**The setup link expired.** Setup links are valid for 8 hours. Return to the Invoca SSO Settings pane, click **Edit SSO Configuration**, and a new 8-hour link generates in a new tab — any progress from your previous session is preserved.

**Locked out due to SSO enforcement.** If SSO enforcement is Mandatory and a misconfiguration locks you out, contact Invoca Support immediately — support can temporarily disable SSO enforcement on your network to restore password-based access while you troubleshoot.


## Related topics

- [SAML SSO: Appendix](/s/article/saml-sso-appendix.md)
- [Legacy SAML SSO Implementation Guide](/s/article/legacy-saml-sso-implementation-guide.md)
- [Configure SSO with Okta](/s/article/configure-sso-with-okta.md)
- [403 Error Logging Into Invoca via SAML/SSO: Invalid Signature](/s/article/403-error-saml-sso-invalid-signature.md)
- [403 Error Logging Into Invoca via SAML/SSO: Required Attributes](/s/article/403-error-saml-sso-required-attributes.md)