# Setting Up SAML/SSO

## Step 1: Download the PixieBrix SAML Metadata File <a href="#block-e0f9eb1a3f0645638965502b32b1edad" id="block-e0f9eb1a3f0645638965502b32b1edad"></a>

Download the metadata file that contains the information your Identity Provider (IdP) needs to establish a secure SAML connection with PixieBrix.

1. Go to <https://app.pixiebrix.com/api/saml/metadata/>
2. Save the XML file to your computer.
3. You'll upload this file to your IdP in Step 2 when creating your SAML application.

## Step 2: Configure your Identity Provider (IdP) <a href="#block-643f7469606a4dbca03271fda830fea5" id="block-643f7469606a4dbca03271fda830fea5"></a>

### Step 2a: Create a SAML Application

Create a new SAML application in your organization's IdP. If your IdP supports uploading metadata, use the PixieBrix metadata file you downloaded in Step 1. Otherwise, create the application manually and enter the details from the metadata file (such as the ACS URL and SP Entity ID).

Follow the setup guide for your IdP:

* [Okta](https://help.okta.com/en-us/content/topics/apps/apps_app_integration_wizard_saml.htm)
* [Azure AD / Microsoft Entra](https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/add-application-portal-setup-sso)
* [Google Workspace](https://support.google.com/a/answer/12032922)
* [JumpCloud](https://jumpcloud.com/support/get-started-applications-saml-sso)

### 2b: Configure Attribute Mapping

PixieBrix requires specific user attributes from your IdP to provision users correctly during SSO login. You'll need to map your IdP's user fields to the standard SAML attributes that PixieBrix expects.

PixieBrix requires the following attribute mappings:

| Service Provider Attribute Name     | Service Provider Attribute Description  |
| ----------------------------------- | --------------------------------------- |
| `urn:oid:0.9.2342.19200300.100.1.1` | Unique User Identifier (e.g., Username) |
| `urn:oid:0.9.2342.19200300.100.1.3` | Email                                   |
| `urn:oid:2.5.4.42`                  | First Name / Given Name                 |
| `urn:oid:2.5.4.4`                   | Last Name / Surname / Family Name       |

Follow your IdP's documentation to configure these mappings and use the tables below as a reference.

#### Okta

See the [Okta](https://support.okta.com/help/s/article/How-to-define-and-configure-a-custom-SAML-attribute-statement?language=en_US) documentation for details.

| Service Provider Attribute Name     | IdP Attribute Name |
| ----------------------------------- | ------------------ |
| `urn:oid:0.9.2342.19200300.100.1.1` | user.login         |
| `urn:oid:0.9.2342.19200300.100.1.3` | user.email         |
| `urn:oid:2.5.4.42`                  | user.firstName     |
| `urn:oid:2.5.4.4`                   | user.lastName      |

#### Azure AD / Microsoft Entra

See the [Azure AD / Microsoft Entra](https://learn.microsoft.com/en-us/entra/external-id/customers/how-to-add-attributes-to-token) documentation for details.

| Service Provider Attribute Name     | IdP Attribute Name     |
| ----------------------------------- | ---------------------- |
| `urn:oid:0.9.2342.19200300.100.1.1` | user.userprincipalname |
| `urn:oid:0.9.2342.19200300.100.1.3` | user.mail              |
| `urn:oid:2.5.4.42`                  | user.givenname         |
| `urn:oid:2.5.4.4`                   | user.surname           |

#### Google Workspace

See the [Google Workspace](https://support.google.com/a/answer/6330801) documentation for details.

| Service Provider Attribute Name     | IdP Attribute Name |
| ----------------------------------- | ------------------ |
| `urn:oid:0.9.2342.19200300.100.1.1` | username           |
| `urn:oid:0.9.2342.19200300.100.1.3` | email              |
| `urn:oid:2.5.4.42`                  | firstName          |
| `urn:oid:2.5.4.4`                   | lastName           |

#### JumpCloud

See the [JumpCloud](https://jumpcloud.com/support/configure-user-attributes-for-saml-connectors) documentation for details.

| Service Provider Attribute Name     | IdP Attribute Name |
| ----------------------------------- | ------------------ |
| `urn:oid:0.9.2342.19200300.100.1.1` | username           |
| `urn:oid:0.9.2342.19200300.100.1.3` | email              |
| `urn:oid:2.5.4.42`                  | first Name         |
| `urn:oid:2.5.4.4`                   | last Name          |

### 2c: Assign Users to the SAML Application

Grant access to the users or groups who should be able to log in via SSO.

Follow your IdP's documentation for assigning users to a SAML application:

* [Okta](https://help.okta.com/en-us/content/topics/users-groups-profiles/usgp-assign-apps.htm)
* [Azure AD / Microsoft Entra](https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/assign-user-or-group-access-portal)
* [Google Workspace](https://support.google.com/a/answer/12032922#assign_profile)
* [JumpCloud](https://jumpcloud.com/support/authorize-users-to-an-sso-application)

## Step 3: Send Identity Provider Configuration to the PixieBrix Support Team <a href="#block-368cb31e471d47e99c83ff0a7c55bd84" id="block-368cb31e471d47e99c83ff0a7c55bd84"></a>

PixieBrix needs certain data from the IdP to complete the integration. Please securely send <support@pixiebrix.com> the following information:

* IdP Entity ID
* IdP URL (aka SSO URL)
* IdP Public Certificate: You can download the public certificate from the IdP.

For example, in JumpCloud, you can download the certificate from the IdP Certificate Valid dropdown, and clicking "Download Certificate”:

<figure><img src="https://images.spr.so/cdn-cgi/imagedelivery/j42No7y-dcokJuNgXeA0ig/26ba33e2-ec85-41d5-89b1-b160809aedf7/Screen_Shot_2023-03-30_at_2.30.31_PM/w=640,quality=80" alt="" width="375"><figcaption><p>Downloading a public IdP certificate from Jump Cloud</p></figcaption></figure>

## Step 4: Test the SAML/SSO Connection <a href="#block-e806cd31c97344ca8b2e1bb503ea0d39" id="block-e806cd31c97344ca8b2e1bb503ea0d39"></a>

After providing the IdP information to the PixieBrix support team in Step 3, the PixieBrix team will provide a URL for the authentication flow.

The sign-in URL the support team provides will have the form: `https://app.pixiebrix.com/login/saml/?idp=<label>,<orgId>`

* `orgId`: your tenant id in PixieBrix
* `label`: a label to distinguish multiple IdP's for a single tenant

## Recommended: Configure the PixieBrix Browser Extension Policy <a href="#block-6336e4a7a6af4404a40e97473ae501a3" id="block-6336e4a7a6af4404a40e97473ae501a3"></a>

You can configure your PixieBrix Browser Extension Policy (Google Workspace or GPO) to automatically authenticate with your configured IdP.

1. Contact <support@pixiebrix.com> to receive the authentication flow URL
2. Set the `ssoUrl` property for the managed browser extension settings. Read more information on IT-managed browser extension configuration in [browser-extension-configuration-policy](https://docs.pixiebrix.com/enterprise-it-setup/browser-extension-installation-and-configuration/browser-extension-configuration-policy "mention")

| Property | Value                                                                                                    |
| -------- | -------------------------------------------------------------------------------------------------------- |
| `ssoUrl` | Authentication flow URL. Will have the form: `https://app.pixiebrix.com/login/saml/?idp=<label>,<orgId>` |

### Troubleshooting

#### Users receive a error for the IdP: "Your administrator has configured the application PixieBrix to block users unless they are specifically granted ("assigned") access to the application"

This IdP error indicates that the user has not been assigned to the SAML application. Refer to Step 2c: Assign Users in the Identity Provider to the SAML Application

#### Users receive a server error from PixieBrix after logging into the Identity Provider

The server error upon IdP login indicates that the user attributes have not been mapped in the Identity Provider property. Refer to Step 2b: Configure the Service Provider Attribute Name Mapping\
\
The PixieBrix platform team is working to improve the error message. In the meantime, contact <support@pixiebrix.com> to receive the error details


---

# Agent Instructions: Querying This Documentation

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

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.pixiebrix.com/enterprise-it-setup/authentication/setting-up-saml-sso.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.