> For the complete documentation index, see [llms.txt](https://docs.userlane.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.userlane.com/deployment/rollout/end-user-single-sign-on.md).

# End-user single sign-on

Configuring SAML-based single sign-on so end users authenticate with their company credentials when the browser extension activates.

Single sign-on (SSO) lets end users authenticate with their company credentials when the Userlane browser extension activates. You configure SSO in the Userlane portal; your IT administrator configures the identity provider side. Once connected, users do not need separate Userlane credentials, and user attributes passed through the sign-in response are available for targeting and analytics.

{% hint style="warning" %}
**Prerequisites.**

* **Admin**, **Deployment Manager**, or **Portfolio Owner** role in the Userlane portal.
* An identity provider (IdP) that supports Security Assertion Markup Language (SAML) 2.0. Userlane works with any SAML 2.0 provider, including Microsoft Entra ID, Google Workspace, Active Directory Federation Services (ADFS), Okta, and OneLogin.
* IT administrator access to the identity provider.
* The browser extension rolled out to users. See [Roll out the extension](/deployment/rollout/roll-out-the-extention.md).
  {% endhint %}

## How end-user SSO works

When a user opens a browser-based application where Userlane is active, the browser extension triggers a SAML authentication flow. The identity provider verifies the user and returns an assertion to Userlane. That assertion identifies the user and can carry additional attributes (department, role, location) that Userlane uses for audience[^1] targeting and analytics filtering.

End-user SSO and portal SSO are configured separately. This article covers end-user SSO only. For portal SSO, see [Portal authentication](/administration/sign-in-and-permissions/portal-authentication.md).

## Set up SSO

Open **Settings** > **Global Settings** > **User Single Sign-On**. The page walks through three steps.

{% stepper %}
{% step %}

#### Share the Userlane metadata with your IT administrator

The page shows two read-only values that your IT administrator needs to add Userlane as a trusted application in the identity provider:

* **Userlane Entity ID**: the identifier for Userlane as a SAML service provider (format: `urn:userlane:saml:sp:company:[id]`)
* **Userlane Consumer URL**: the endpoint where the IdP sends the SAML assertion

Copy each value using the copy button next to the field, or select **Download as XML** to export the full metadata file. Send these to your IT administrator.

Your IT administrator adds Userlane as a SAML application in the identity provider using these values. The exact steps depend on the provider:

{% tabs %}
{% tab title="Microsoft Entra ID" %}
Add Userlane as an enterprise application in Entra ID. Paste the Entity ID and Consumer URL into the SAML configuration. Entra ID certificates default to 3 years before expiry.
{% endtab %}

{% tab title="Google Workspace" %}
Add Userlane as a custom SAML app in the Google Admin console. Paste the Entity ID and Consumer URL into the service provider details. Google Workspace certificates default to 5 years before expiry.
{% endtab %}

{% tab title="ADFS" %}
Add Userlane as a relying party trust. Import the downloaded XML metadata file, or enter the Entity ID and Consumer URL manually. Configure a claim rule to pass the NameID.
{% endtab %}

{% tab title="Other SAML 2.0 providers" %}
Add Userlane as a SAML service provider using the Entity ID and Consumer URL. The metadata XML file works with any provider that supports SAML 2.0 metadata import.
{% endtab %}
{% endtabs %}
{% endstep %}

{% step %}

#### Enter the identity provider metadata into Userlane

Once your IT administrator has configured the identity provider, you need two values from them:

* **IDP Entrypoint URL (for SAML)**: the URL where Userlane sends authentication requests
* **IDP Certificate**: the X.509 certificate the identity provider uses to sign assertions

Enter both values on the **User Single Sign-On** page under step 2, **Configure SSO**. Select **Save Changes**.

{% hint style="info" %}
**Certificate expiry.** IdP certificates expire and need periodic renewal. The default expiry is 3 years for Microsoft Entra ID and 5 years for Google Workspace, though your IT administrator can set a custom expiry. When a certificate is about to expire, update it here before the old one lapses to avoid interrupting authentication.
{% endhint %}
{% endstep %}

{% step %}

#### Test the connection

After saving, select **Test SSO** under step 3, **Test the SSO integration**. The test runs the full authentication flow: Userlane redirects to the identity provider, the IdP authenticates you, and you are redirected back to the browser extension. If the test completes without errors, SSO is working.

If the test fails, check that the Entity ID and Consumer URL in the identity provider match the values on the Userlane page exactly, and that the certificate was pasted in full.
{% endstep %}
{% endstepper %}

## Choose the SSO window mode

The SSO window mode[^2] controls how the browser extension opens the identity provider's login page. You can find this setting under **Settings** > **Global Settings** > **Browser Extension**. The default works for most providers, but some combinations require a different mode.

<table><thead><tr><th width="136.8095703125">Mode</th><th width="301.1962890625">Behavior</th><th>When to use</th></tr></thead><tbody><tr><td><strong>Iframe</strong></td><td>Opens the IdP login inside a hidden iframe. Authentication happens invisibly.</td><td>Default. Works for most identity providers.</td></tr><tr><td><strong>Inactive Tab</strong></td><td>Opens a background tab for login, then closes it after authentication.</td><td>Use when Iframe does not work. Required for Microsoft Entra ID, which blocks iframe-based login.</td></tr><tr><td><strong>Active Tab</strong></td><td>Opens a foreground tab for login. The user sees the IdP login page directly.</td><td>Use when the IdP requires visible user interaction beyond credentials, such as a multi-factor authentication prompt.</td></tr></tbody></table>

## Set the refresh interval

The refresh interval controls how often the browser extension re-authenticates with the identity provider to pick up updated attributes. You can find it under **Settings** > **Global Settings** > **Browser Extension**, alongside the window mode setting. The options range from disabled (attributes are read once and never refreshed) through daily, every other day, and weekly. A shorter interval keeps attribute values more current but sends more authentication requests to the identity provider.

## Pass user attributes through SSO

SSO can carry more than identity. If the SAML assertion includes additional claims (department, location, job title, or any custom value), Userlane creates matching user attributes automatically. These attributes power audience rules and appear in analytics.

To verify which attributes are arriving, go to **Settings** > **Company Users** and check the attribute columns for a user who has authenticated. If an expected attribute is missing, confirm with your IT administrator that the claim is included in the SAML assertion.

For more on how attributes work and how to manage them, see [Attributes](/administration/attributes.md) and [Attributes from SSO](/administration/attributes/attributes-from-sso.md).

## Troubleshooting

<table><thead><tr><th width="194.900390625">Symptom</th><th>Likely cause</th><th>Resolution</th></tr></thead><tbody><tr><td>Test SSO fails immediately</td><td>Entity ID or Consumer URL mismatch between Userlane and the IdP</td><td>Compare the values on the <strong>User Single Sign-On</strong> page with what is configured in the identity provider. They must match exactly.</td></tr><tr><td>Test SSO redirects but returns an error</td><td>Certificate mismatch or incomplete certificate</td><td>Re-copy the full IDP Certificate from the identity provider and paste it into Userlane. Make sure no characters were truncated.</td></tr><tr><td>Users are not prompted to authenticate</td><td>SSO is saved but not enabled, or the browser extension is not installed</td><td>Confirm SSO is enabled on the <strong>User Single Sign-On</strong> page. Confirm the browser extension is installed and active.</td></tr><tr><td>Attributes are missing in Company Users</td><td>The IdP assertion does not include the expected claims</td><td>Ask the IT administrator to confirm the claims are included in the SAML assertion for Userlane.</td></tr><tr><td>Authentication works but expires too quickly</td><td>Refresh interval is set too short, or IdP session length is short</td><td>Adjust the refresh interval. Check the IdP's session timeout setting.</td></tr></tbody></table>

For error messages and extension-side checks, see [Troubleshoot the extension](/deployment/rollout/roll-out-the-extention/troubleshoot-the-extension.md).

## Relevant articles

{% content-ref url="/pages/010elIp8D0o8LOTk7kQz" %}
[Portal authentication](/administration/sign-in-and-permissions/portal-authentication.md)
{% endcontent-ref %}

{% content-ref url="/pages/eDKAypFN3hxD4iC2VJll" %}
[Attributes from SSO](/administration/attributes/attributes-from-sso.md)
{% endcontent-ref %}

{% content-ref url="/pages/ZbAA5aBZMukn2qqLRZji" %}
[Roll out the extension](/deployment/rollout/roll-out-the-extention.md)
{% endcontent-ref %}

{% content-ref url="/pages/FRU06enU3lsRJrh5njNu" %}
[Troubleshoot the extension](/deployment/rollout/roll-out-the-extention/troubleshoot-the-extension.md)
{% endcontent-ref %}

## FAQ

<details>

<summary>Which identity providers does Userlane support?</summary>

Any provider that supports SAML 2.0. This includes Microsoft Entra ID, Google Workspace, ADFS, Okta, OneLogin, and others. Userlane does not restrict the provider; it accepts any valid SAML 2.0 assertion.

</details>

<details>

<summary>What is the difference between end-user SSO and portal SSO?</summary>

End-user SSO authenticates people using browser-based applications where the Userlane extension is active. Portal SSO authenticates administrators and team members signing in to the Userlane portal. The two are configured separately.

</details>

<details>

<summary>Does end-user SSO work on Firefox?</summary>

Yes. SAML-based SSO works on Chrome, Edge, and Firefox.

</details>

<details>

<summary>What happens if a user is not in the identity provider?</summary>

They cannot authenticate. The browser extension retries at increasing intervals. See [Troubleshoot the extension](/deployment/rollout/roll-out-the-extention/troubleshoot-the-extension.md).

</details>

<details>

<summary>What happens when the IdP certificate expires?</summary>

Authentication stops working until the certificate is renewed. Update the **IDP Certificate** field on the **User Single Sign-On** page with the new certificate before the old one expires to avoid an interruption.

</details>

<details>

<summary>How often are user attributes refreshed?</summary>

According to the refresh interval you choose: daily, every other day, weekly, or disabled. A shorter interval keeps attributes more current but sends more requests to the identity provider.

</details>

[^1]: An audience is a reusable group of end users defined by attribute rules, used to control who sees which content.

[^2]: The SSO window mode controls how the browser extension opens the identity provider's login page: invisibly in an iframe, in a background tab (Inactive Tab), or in a focused tab (Active Tab). The choice depends on what the identity provider allows.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.userlane.com/deployment/rollout/end-user-single-sign-on.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.