Setting Up SAML/SSO

Step 1: Download the PixieBrix SAML Metadata File

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)

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

• Azure AD / Microsoft Entra

• Google Workspace

• JumpCloud

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 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 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 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 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

• Azure AD / Microsoft Entra

• Google Workspace

• JumpCloud

Step 3: Send Identity Provider Configuration to the PixieBrix Support Team

PixieBrix needs certain data from the IdP to complete the integration. Please securely send [email protected] 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”:

Downloading a public IdP certificate from Jump Cloud

Step 4: Test the SAML/SSO Connection

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

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

1. Contact [email protected] 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

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 [email protected] to receive the error details