> 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/administration/sign-in-and-permissions/portal-authentication.md).
# Portal authentication
Enabling SSO for portal administrators, how it differs from end-user SSO, and turning on two-factor authentication.
Userlane offers two ways to strengthen how team members sign in to the portal: single sign-on (SSO) through the organization's identity provider[^1], and two-factor authentication (2FA) as a second verification step. Both are optional and can run together.
End-user authentication through the browser extension is a separate configuration covered in [End-user single sign-on](/deployment/rollout/end-user-single-sign-on.md).
{% hint style="warning" %}
**Before you start.** You need the **Admin** role in the Userlane portal. SSO setup also requires an IT administrator with access to the organization's identity provider (any provider that supports Security Assertion Markup Language (SAML) 2.0).
{% endhint %}
## Set up single sign-on
Portal SSO lets team members sign in with their company credentials instead of a separate Userlane password. Once enabled, the identity provider handles sign-in for all team members except those with **Bypass SSO**.
Go to **Settings** > **Team management** and select **Set up Single Sign-On**. The setup runs in three steps.
{% stepper %}
{% step %}
#### Share the Userlane metadata with your IT administrator
The **Team Single Sign-On** page opens with the Userlane **Entity ID** and **Consumer URL** at the top. Your IT administrator needs this information to add Userlane as a trusted application in the identity provider. Either copy the link or download the metadata as an XML file using the buttons provided, then pass the file or link to IT.
{% endstep %}
{% step %}
#### Enter the identity provider metadata
Once your IT administrator has configured Userlane in the identity provider, they supply metadata in return. You can upload the metadata XML file directly using **Upload IDP Metadata**, or enter the values manually in three fields:
* **Identity Provider Entity ID**: the unique identifier for the identity provider.
* **SSO Service URL**: the endpoint where Userlane sends authentication requests.
* **X509 Certificate**: the public certificate Userlane uses to verify responses from the identity provider.
Make sure the identity provider sends the user's email address as the SAML NameID. Userlane matches team members by email, so a different identifier (such as an employee number) prevents the match.
Select **Save Configuration** when the fields are complete. Saving does not enable SSO, so existing logins continue working.
{% endstep %}
{% step %}
#### Enable single sign-on
Toggle **Enable Single Sign-On** to on. The identity provider now handles sign-in for all team members who do not have **Bypass SSO**.
Test the connection by signing out and signing back in. If the identity provider redirects you back to the portal without prompting for Userlane credentials, SSO is working.
{% endstep %}
{% endstepper %}
{% hint style="info" %}
**Provider-specific notes.** Userlane supports any identity provider that uses SAML 2.0. Active Directory Federation Services (ADFS), Microsoft Entra ID, Google Workspace, Okta, and OneLogin all work. If your provider requires a specific Recipient URL or SAML Initiator setting, use the **Entity ID** and **Consumer URL** from step one.
{% endhint %}
## Bypass SSO
**Bypass SSO** allows a team member to sign in with their email and password even when SSO is active. It covers two situations: recovering from a broken SSO configuration (an expired certificate, a misconfigured identity provider), and giving access to people outside the organization's identity provider, such as external contractors or Userlane support.
**Admin** role users always have **Bypass SSO** enabled and cannot turn it off. This means at least one person can always reach the portal to fix a broken SSO configuration.
To enable **Bypass SSO** for a non-admin team member, open their entry on the **Team management** page, select the three-dot menu, and switch on **Bypass SSO** in their permissions.
## Modify or disable SSO
To update an expired certificate or change the identity provider, return to **Settings** > **Team management** > **Set up Single Sign-On** and edit the relevant fields. Save the updated configuration.
To disable SSO entirely, toggle **Enable Single Sign-On** to off. Team members revert to signing in with their email and password. The saved identity provider configuration stays in place so you can re-enable SSO later without entering the metadata again.
{% hint style="danger" %}
**Deleting the configuration is permanent.** If you delete the SSO configuration rather than disabling it, Userlane removes all identity provider metadata. You need to complete the full setup again.
{% endhint %}
## Set up two-factor authentication
Two-factor authentication adds a one-time code to the sign-in process, whether team members use SSO or a password. Userlane uses time-based one-time passwords (TOTP), which work with standard authenticator apps: Microsoft Authenticator, Google Authenticator, FreeOTP, or any app that supports TOTP codes.
2FA is a company-level setting. Once you turn it on, every team member must set up their authenticator app on their next sign-in.
{% stepper %}
{% step %}
#### Enable 2FA for the company
Go to **Settings** > **Team management**. In the **2-Factor Authentication** card, select **Enable Authentication**. A confirmation dialog explains that all team members must configure 2FA on their next login.
{% endstep %}
{% step %}
#### Team members configure their authenticator app
On the next sign-in, each team member sees a setup screen with a QR code. They scan the code with their authenticator app, then enter the six-digit code the app generates to confirm the pairing. From that point on, every login requires both credentials and a one-time code.
{% endstep %}
{% endstepper %}
The **2FA** column on the **Team management** page shows the status for each team member: a dash means the member has not yet completed setup, and a check means the pairing is active.
## Recover access
Three scenarios can lock a team member out, and each has a recovery path.
**SSO is broken** (expired certificate, misconfigured identity provider): the bypass admin signs in with their email and password, navigates to **Team management** > **Set up Single Sign-On**, and corrects the configuration. Because **Admin** role users always have **Bypass SSO**, at least one person can get in.
**A team member loses access to their authenticator app**: an **Admin** user opens the locked-out member's entry on the **Team management** page, selects the three-dot menu, and resets 2FA for that user. The member then pairs a new authenticator app on their next login.
**A team member forgets their password** (non-SSO accounts only): the standard password reset link on the portal login page sends a reset email to the registered address.
## Relevant articles
{% content-ref url="/pages/IkbYytjTIP1b0c4ZNCbM" %}
[End-user single sign-on](/deployment/rollout/end-user-single-sign-on.md)
{% endcontent-ref %}
{% content-ref url="/pages/T6JBjNnsSjhJFPji2nUG" %}
[Set up the account](/getting-started/first-steps-in-the-portal/set-up-the-account.md)
{% endcontent-ref %}
{% content-ref url="/pages/x0VOtqZaqLMPxH6L3eGw" %}
[Contact and escalation](/support/contact-and-escalation.md)
{% endcontent-ref %}
## FAQ
Can SSO and 2FA be used together?
Yes. SSO handles identity through the organization's provider, and 2FA adds a second verification step on top. When both are active, team members authenticate with the identity provider first, then enter a one-time code from their authenticator app.
What happens if the SAML certificate expires?
Team members who rely on SSO cannot sign in until the certificate is renewed. The bypass admin signs in with their email and password, uploads the renewed certificate on the **Team Single Sign-On** page, and saves the configuration. SSO resumes immediately.
Can 2FA be required for some team members but not others?
No. 2FA is enabled at the company level and applies to all team members. There is no per-user override.
Which authenticator apps are supported?
Any app that generates TOTP codes: Microsoft Authenticator, Google Authenticator, FreeOTP, or similar. Hardware TOTP tokens that display a six-digit code also work.
What is the difference between portal SSO and end-user SSO?
Portal SSO authenticates team members signing in to the Userlane portal to manage content, view analytics, and configure settings. End-user SSO authenticates the people who use the browser extension on the organization's applications. The two are configured separately.
[^1]: An identity provider (IdP) is the system that manages your organization's user accounts and sign-in, such as Microsoft Entra ID, Okta, or Google Workspace.
---
# 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/administration/sign-in-and-permissions/portal-authentication.md?ask=&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.