# Implement SSO authentication

> Learn how to set up Single Sign-On (SSO) in PandaSuite using SAML v2 or OpenID Connect (OIDC) to let users sign in with your company identity provider (IdP).

https://docs.pandasuite.com/account/security/implement-sso-authentication-with-saml-v2/

**Single Sign-On (SSO) allows users to log in to PandaSuite using their corporate identity, without needing to create an additional account.** PandaSuite supports both **SAML v2** and **OpenID Connect (OIDC)**, used by many identity providers (IdP) such as Azure AD, Google Workspace, Okta, Auth0, etc.

SSO can be enabled in two places:

- **On the editor side** → For users accessing PandaSuite Studio.
- **On the web app side** → For applications created with PandaSuite (Web App / PWA).

These two configurations are independent. You can enable SSO for Studio, for a web app, or both. For each area, you choose one protocol (**SAML** or **OIDC**).

## What is SSO?

**Single Sign-On (SSO)** is an authentication method that allows users to securely log in to **multiple applications** with a single credential.

### Why use SSO?

- **Enhanced security**: fewer passwords to manage, reducing the risk of phishing.
- **Seamless experience**: smooth login without repeated authentication.
- **Centralized management**: access controlled by the IT administrator via an IdP.

### The SAML v2 protocol

SAML (**Security Assertion Markup Language**) is an **XML standard** that allows a **service provider** (*SP*), like PandaSuite, to **delegate authentication** to an **identity provider** (*IdP*).

### The OpenID Connect (OIDC) protocol

OpenID Connect (**OIDC**) is a modern protocol built on OAuth 2.0. It allows a service provider (like PandaSuite) to delegate authentication to an identity provider and receive standardized identity information (claims).

## How does SSO work?

SSO is based on **a secure exchange of authentication tokens** between **PandaSuite** and your identity provider (**IdP**).

1. The user attempts to access PandaSuite or a web app.
2. PandaSuite redirects the user to the IdP and asks it to authenticate them.
3. The IdP checks if the user is already logged in:
   - ✅ If yes, access is granted immediately.
   - 🔄 Otherwise, they are redirected to their company’s login page.
4. The user authenticates with their IdP (e.g., Microsoft 365, Google, Okta credentials, etc.).
5. The IdP validates the identity and sends authentication information back to PandaSuite (SAML assertion or OIDC token).
6. PandaSuite validates it and grants access to the user.

> **Tip**
>
> Everything happens in the background, without the user having to enter a
> password on PandaSuite!

## Setting up SSO for a web app

> **Warning**
>
> Currently, SSO authentication is **only compatible with web apps / PWA**. For
> a native application, please contact our team.

1. **Retrieve PandaSuite information**

   - Access your PandaSuite account
   - Go to the **Apps** section and select your web app
   - In **Services**, click **Security**
   - Turn on **Enable SSO**
   - Select a **Protocol** (**SAML** or **OIDC**)

   PandaSuite automatically provides you with the following information (depending on the selected protocol):

   - **SAML**
     - **Metadata URL**: `https://pandasuite.com/secure/saml/[APP_ID]/metadata`
     - **Entity ID**: `https://pandasuite.com/launcher/c/[APP_ID]`
     - **Assertion Consumer Service URL**: `https://pandasuite.com/secure/saml/[APP_ID]/consume`
   - **OIDC**
     - **Callback URL**: `https://pandasuite.com/secure/oidc/callback`

[Image: Security page of a web app: the framed SSO box lists the Metadata URL, Entity ID and ACS URL; below, Enable SSO is on, with SAML and OIDC]

2. **Configure your identity provider (IdP)**

   Use the information above to configure your PandaSuite application in your identity provider (Azure AD, Google Workspace, Okta, etc.).

3. **Finalize the configuration in PandaSuite**
   - If you selected **SAML**:
     - In **Configuration type**, choose **Dynamic URL** to paste the **IdP Metadata URL**, or choose **Metadata file** to upload your metadata file.
     - Optional: enable **Sign AuthnRequests** if your identity provider requires PandaSuite to sign SAML authentication requests.
     - Optional: enable **Require signed assertions** to reject SAML assertions that are not signed by your identity provider.
     - If **Sign AuthnRequests** is enabled:
       - PandaSuite generates a signing certificate when you save the configuration.
       - Prefer the PandaSuite **Metadata URL** when your identity provider can refresh it automatically. Use **Download PEM certificate** only when you need a manual certificate import.
       - Add one or more email addresses in **Certificate expiry notifications** to receive reminders 30 days and 7 days before the active certificate expires.
       - When PandaSuite prepares a replacement certificate, it appears as **Next**. Import it into your identity provider before selecting it in PandaSuite. PandaSuite does not switch certificates automatically.
   - If you selected **OIDC**:
     - Fill in **Issuer URL**, **Client ID**, and **Client Secret**.
     - If a client secret is already configured, leave **Client Secret** empty to keep it unchanged.
     - Optional: adjust **Scopes** (default: `openid`, `email`, `profile`) and **User ID Claim** (default: `sub`).
   - Save the configuration and test the connection. If your account uses [two-step authentication](https://docs.pandasuite.com/account/security/two-step-authentication/), PandaSuite first asks you to confirm your identity in the **Verification required** window.

### Optional: Restrict access with Access Rules

On the **Security** page, you can create **Access Rules** to restrict access based on:

- **SAML** attributes (including the **NameID** field)
- **OIDC** claims (including the **Subject (sub)** claim)

Under **Access Rules**, click **Add Rule**, then fill in:

- **Field Name**: the value to check. Choose **Use the NameID field** (SAML) or **Use the Subject (sub) claim** (OIDC), or choose **Custom attribute** / **Custom claim** and enter its **Attribute Name** / **Claim Name** (for example `email` or `role`).
- **Channel**: apply the rule to **All channels** or to a single channel of your app. A rule on the NameID field or the Subject (sub) claim always applies to all channels. For a custom attribute or claim, a rule set for a channel replaces the **All channels** rule of the same field on that channel.
- **Whitelist (allowed patterns)**: one pattern per line. When this list is filled in, the visitor's value must match at least one of its patterns.
- **Blacklist (blocked patterns)**: one pattern per line. A visitor whose value matches one of these patterns is refused.

Each pattern is a regular expression, searched anywhere in the value and case-sensitive: `@company\.com$` matches every address of that domain (`\.` stands for a literal dot, `$` for the end of the value). To match any characters, use `.*`, not `*`: a pattern that is not a valid regular expression, such as one that starts with `*`, never matches. When several rules apply, the visitor must satisfy all of them. A visitor whose identity provider does not send the checked field is refused.

## Use the visitor identity in your app

Once SSO is enabled on your web app, your project can read the visitor's attributes and prove their identity to other services.

### Expose SSO attributes to your project

In PandaSuite Studio, open the [project properties](https://docs.pandasuite.com/essentials/project-properties/project-properties-and-actions/) and add the attribute names you need (for example `email` or `role`) in the **SSO parameters** field. Only the attributes you declare are shared with the project. Their values appear in the data binding tree under `Project > SSO parameter(s) > ...`, ready to display or reuse in your project.

> **Info**
>
> Declaring a name filters what reaches the project: it does not make your
> identity provider send it. Ask whoever manages your IdP which attributes are
> released to the app, and declare exactly those names. A declared attribute
> that stays empty means the IdP does not send it under that name.

### Get a verifiable proof of identity

Your app may need to prove to another service who the visitor is: your own backend, an API, or a custom component. Attribute values are not a proof, since anything readable in the app can be copied. For a real proof, add the reserved name `pandasuiteIdentityAssertion` to the same **SSO parameters** field.

*For example, your backend can unlock content reserved for your customers when the token's `sub` matches an account you already know.*

When a visitor signs in through SSO, PandaSuite places a signed token under that name, next to the other declared attributes. To send it, bind the `pandasuiteIdentityAssertion` value into an [HTTP component](https://docs.pandasuite.com/essentials/components/http/) request or into a custom component property. Send it within five minutes of the app loading, and do not store it for later: past that delay, your service will reject it as expired. Every load of the app during an active SSO session receives a fresh token.

You declare the name in Studio. Verifying the token is a developer's job: give your developer the details below.

| The token at a glance      | Details                                                                                                                            |
| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| Format                     | JWT signed by PandaSuite (RS256, `typ` header: `pandasuite-identity+jwt`)                                                          |
| Lifetime                   | 5 minutes                                                                                                                          |
| Verification               | offline, against the public keys published at `https://pandasuite.com/.well-known/jwks.json`, checking that `aud` matches your app |
| `sub`                      | a stable, anonymous identifier of the visitor (it starts with `psid_`), never the raw identifier from your IdP                     |
| `auth_time`                | when the visitor signed in at the identity provider; require a recent value if your service needs a fresh sign-in                  |
| `email` and `attributes`   | included only when you also declare those attribute names                                                                          |
| `aud` and `publication_id` | identify where the sign-in took place (the app or the publication)                                                                 |
| `channel_id`               | present only when the visitor signed in through your app, absent for a direct publication link                                     |

## Setting up SSO to access PandaSuite Studio

> **Info**
>
> The PandaSuite team first creates your SSO organization. You then fill in its
> configuration yourself, as the owner of the organization.

1. **Request creation of your organization**

   - **Contact the PandaSuite team** to request the creation of your SSO organization.
   - Once it is created, open it from the dashboard: click your name at the bottom left, then **Account**. In the **Enterprise** tab, click your organization. Read [Manage your organization](https://docs.pandasuite.com/account/account/manage-your-organization/) for its members and licenses.

2. **Retrieve PandaSuite information**

   In the **Single Sign-On** section, select a **Protocol** (**SAML** or **OIDC**), then click **Show SAML configuration** or **Show OIDC configuration**. PandaSuite gives you the following information:

   - **SAML**: **Identifier (Entity ID)**, **Assertion Consumer Service URL**, and **Metadata URL**
   - **OIDC**: **Callback URL**

3. **Configure your identity provider (IdP)**

   Use this information to configure PandaSuite Studio in your identity provider (Azure AD, Google Workspace, Okta, etc.).

4. **Enter the IdP information**

   - If you selected **SAML**: in **Configuration type**, choose **Dynamic URL** and paste the **IdP Metadata URL**, or choose **Metadata file** and import the XML metadata file of your identity provider. Under **Request & response signing**, turn on **Sign AuthnRequests** and/or **Require signed assertions** if your identity provider needs them.
   - If you selected **OIDC**: fill in the **Issuer URL**, **Client ID**, and **Client Secret** (and optional **Scopes** and **Email Claim**).
   - Click **Save SSO**.
   - If your account uses [two-step authentication](https://docs.pandasuite.com/account/security/two-step-authentication/), **Verification required** opens first: confirm your identity, then click **Save SSO** again. From PandaSuite Studio, a security key cannot be used for this check: if it is your only second factor, open the dashboard in a web browser.

[Image: Single Sign-On section of an organization: SAML protocol, PandaSuite information, and the framed Configuration type and IdP Metadata URL]

5. **Finalization**

   Once the configuration is complete, your users can sign in to PandaSuite Studio with SSO. The switch next to **Single Sign-On** shows whether SSO is active for your organization: you cannot change it yourself. Contact the PandaSuite team if you need help.

   If your Studio SSO uses **SAML** request signing, PandaSuite can also expose the signing certificate through the **Metadata URL** or a downloadable PEM file, plus **Certificate expiry notifications** to help you prepare the rotation. When PandaSuite prepares a replacement certificate, it appears as **Next**. Import it into your identity provider before activating it in PandaSuite.