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

# Single sign-on

> Let your team sign in to the Partner Portal through your own identity provider with SAML 2.0 or OpenID Connect.

Single sign-on (SSO) lets your team sign in to the [LI.FI Partner Portal](https://portal.li.fi/) with the credentials they already use at work. You connect your identity provider (IdP) once, and members whose email matches your company domains sign in through it.

The portal supports two protocols: **OpenID Connect (OIDC)** and **SAML 2.0**. Both work with Okta, Microsoft Entra ID, Google Workspace, and any other standards-compliant provider. If you have no preference, use OIDC. It needs one URL and a set of credentials, with no certificates to rotate.

## Before you start

* You are an **Owner** of your organisation in the Partner Portal. Only Owners can see and edit SSO settings.
* SSO is enabled for your organisation. Open **Settings → Single sign-on**. If the page shows **Request access**, [contact the LI.FI team](https://li.fi/contact-us/) and we enable it for you.
* You have admin access to your identity provider, or someone who does.
* You know the email domains your team uses, for example `example.com` and `example-corp.com`.

## How sign-in works

Sign-in always starts at the portal. Members open [portal.li.fi](https://portal.li.fi/) and enter their work email.

* In **Required** mode, members whose email matches one of your domains are redirected to your identity provider automatically.
* In **Optional** mode, members see a **Continue with SSO** option under the password field and choose how to sign in.

**Settings → Single sign-on** also shows an **SSO sign-in link** while your connection is active. Share it with your team to start an SSO sign-in directly. It does not appear on the public login page.

<Note>
  Sign-in that starts from your identity provider, such as an Okta or Entra application tile, is not supported. Members must start at the portal or use the SSO sign-in link.
</Note>

The email address is the account key. Your identity provider must release the user's email on every sign-in, or the portal cannot match the user to your organisation.

## Set up OpenID Connect

### In your identity provider

<Steps>
  <Step title="Create a web application">
    Create a new OIDC application of type **Web** (also called *confidential client*). Enable the **Authorization Code** grant. The implicit grant is not used.
  </Step>

  <Step title="Register both redirect URIs">
    Add both of these as allowed redirect (callback) URIs:

    ```text theme={"system"}
    https://auth-prod.portal.li.fi/login/callback
    https://lifi-prod.eu.auth0.com/login/callback
    ```
  </Step>

  <Step title="Allow the required scopes">
    Grant the `openid`, `profile`, and `email` scopes. The `email` claim must be present in the ID token.
  </Step>

  <Step title="Leave initiate-login and sign-out URLs empty">
    The portal does not use an initiate-login URI or a sign-out URL. Leave them blank.
  </Step>

  <Step title="Copy the credentials">
    Note the **Client ID** and **Client Secret**, and your provider's discovery URL. It has the form `https://<your-idp>/.well-known/openid-configuration`.
  </Step>
</Steps>

### In the Partner Portal

<Steps>
  <Step title="Open the SSO settings">
    Go to **Settings → Single sign-on** and select **OpenID Connect** as the protocol.
  </Step>

  <Step title="Enter the discovery URL">
    Paste your provider's `/.well-known/openid-configuration` URL into **Discovery URL**. The issuer, signing keys, and endpoints are resolved from it.
  </Step>

  <Step title="Enter the credentials">
    Fill in **Client ID** and **Client Secret**. The secret is never shown again after saving. Enter a new value only when you rotate it.
  </Step>

  <Step title="Add your email domains">
    Under **Email domains**, enter one domain per line. Members with a matching email are routed to your identity provider.
  </Step>

  <Step title="Save">
    Click **Save**. Then follow [Choose an SSO mode](#choose-an-sso-mode) to turn SSO on.
  </Step>
</Steps>

<Note>
  The **Service provider metadata** card on the same page (SP Entity ID, ACS URL, SAML metadata URL) applies to SAML only. You can ignore it for OIDC.
</Note>

## Set up SAML 2.0

### Copy the service provider details

<Steps>
  <Step title="Open the SSO settings">
    Go to **Settings → Single sign-on** and select **SAML 2.0** as the protocol.
  </Step>

  <Step title="Copy the values from Service provider metadata">
    The card shows your organisation's **SP Entity ID**, **Assertion Consumer Service (ACS) URL**, and **SAML metadata URL**. They have this shape, where `org-<your-org-id>` is specific to your organisation:

    ```text theme={"system"}
    SP Entity ID       urn:auth0:lifi-prod:org-<your-org-id>
    ACS URL            https://auth-prod.portal.li.fi/login/callback?connection=org-<your-org-id>
    SAML metadata URL  https://auth-prod.portal.li.fi/samlp/metadata?connection=org-<your-org-id>
    ```

    Copy the values from your own settings page rather than from this example.
  </Step>
</Steps>

### In your identity provider

<Steps>
  <Step title="Create a SAML 2.0 application">
    If your provider accepts a metadata URL, paste the **SAML metadata URL** and the rest is filled in for you. Otherwise enter the **SP Entity ID** as the audience and the **ACS URL** as the single sign-on or reply URL.
  </Step>

  <Step title="Set the Name ID to the user's email">
    Use the email address as the Name ID, with the `emailAddress` format.
  </Step>

  <Step title="Add attribute statements">
    Add an attribute named `email` that carries the user's email address. Optionally add `given_name` and `family_name` for the user's first and last name.

    <Warning>
      The Name ID alone is not enough. If your identity provider does not send the email as an attribute, members are created without an email address and cannot use the portal.
    </Warning>
  </Step>

  <Step title="Download the IdP metadata">
    Most providers offer a metadata XML file or URL for the application. Download it, or note the **Entity ID**, **sign-in URL**, and **X.509 signing certificate**.
  </Step>
</Steps>

### Back in the Partner Portal

<Steps>
  <Step title="Paste the IdP metadata XML">
    Paste the full metadata XML from your identity provider into **IdP metadata XML**. The fields below it are populated from the metadata when you save.

    If you have no metadata file, fill in **IdP Entity ID**, **IdP Sign-in URL**, and **X.509 signing certificate** (PEM format, including the `BEGIN CERTIFICATE` and `END CERTIFICATE` lines). **IdP Sign-out URL** is optional.
  </Step>

  <Step title="Map the attributes">
    Set **Email attribute** to the attribute name that carries the email in your assertion. The default is `email`. Optionally set **First name attribute** and **Last name attribute**.
  </Step>

  <Step title="Add your email domains">
    Under **Email domains**, enter one domain per line.
  </Step>

  <Step title="Save">
    Click **Save**. Then follow [Choose an SSO mode](#choose-an-sso-mode) to turn SSO on.
  </Step>
</Steps>

## Choose an SSO mode

The **SSO mode** card controls how members of your organisation can sign in.

| Mode         | Behaviour                                                                      |
| ------------ | ------------------------------------------------------------------------------ |
| **Disabled** | Standard sign-in only. SSO is configured but inactive.                         |
| **Optional** | Members can sign in via SSO or password. Use during rollout.                   |
| **Required** | Members must sign in via SSO. Password login is blocked for this organisation. |

We recommend this rollout:

1. Save your connection and switch to **Optional**.
2. Sign in through your identity provider with one member to confirm the connection works.
3. Switch to **Required**.

<Warning>
  In **Required** mode, everyone in your organisation must sign in through your identity provider from their next sign-in onwards, and anyone whose email matches your domains is redirected to it automatically. Test the connection in Optional mode first.
</Warning>

## Troubleshooting

<AccordionGroup>
  <Accordion title="“IdP-Initiated login is not enabled for connection …”">
    The member started the sign-in from your identity provider, for example an Okta or Entra tile. Start at [portal.li.fi](https://portal.li.fi/) or use the **SSO sign-in link** from your settings page instead.

    In Okta, you can make the tile work by opening the application's **General** settings, setting **Login initiated by** to *Either Okta or App*, ticking **Redirect to app to initiate login (SP-initiated)**, and setting the **Login URL** to `https://portal.li.fi`.
  </Accordion>

  <Accordion title="Entering my email does not redirect to our identity provider">
    Automatic redirection only happens in **Required** mode. In **Optional** mode, choose **Continue with SSO** under the password field, or switch the mode to Required.
  </Accordion>

  <Accordion title="“An error occurred during the authorization flow” (OIDC)">
    Your identity provider rejected the request. Check that both redirect URIs are registered on the application and that the **Authorization Code** grant is enabled.
  </Accordion>

  <Accordion title="“We couldn’t finish your single sign-on”">
    The account returned by your identity provider could not be matched to your organisation. Check that the email it releases matches one of your configured **Email domains**. If it does, [contact the LI.FI team](https://li.fi/contact-us/).
  </Accordion>

  <Accordion title="A member signed in but has no name or email">
    For SAML, check the attribute statements and the **Email attribute**, **First name attribute**, and **Last name attribute** mapping. For OIDC, make sure the application grants the `profile` and `email` scopes.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="Partner Portal changelog" icon="list" href="/changelog/partner-portal">
    Follow additions and updates to the Partner Portal.
  </Card>

  <Card title="Contact the LI.FI team" icon="envelope" href="https://li.fi/contact-us/">
    Request SSO for your organisation or get help with your setup.
  </Card>
</CardGroup>