PixieBrix Docs
CommunityTemplates
Ask or search…
⌃K
Links
Comment on page

Setting Up SAML/SSO

Step 1: Download the PixieBrix Service Provider (SP) Metadata

  1. 1.
    Visit the SAML Service Provider (SP) Metadata link: https://app.pixiebrix.com/api/saml/metadata/​
  2. 2.
    Download to a file. In Step 2, you will upload the metadata file to your Identity Provider (IDP)

Step 2: Configure your Identity Provider (IDP)

The documentation uses JumpCloud as an IDP in the example below. However, the configuration should be similar for any vendor. Please feel free to contact [email protected] if you have any questions/concerns.

Step 2a: Create a SAML App in your IDP

  1. 1.
    Login to JumpCloud as an Administrator: https://console.jumpcloud.com/login/admin​
    image
    ​
  2. 2.
    Click “SSO” on the left side panel. Then click “Add New Application” > “Custom SAML App”
    image
    ​
  3. 3.
    “General Info” tab Display Name: PixieBrix
  4. 4.
    “SSO” tab
    1. 1.
      In another tab, navigate to https://app.pixiebrix.com/api/saml/metadata/ and save the metadata to a file
    2. 2.
      Upload Metadata: Then upload the metadata to JumpCloud.
      image
       Uploading the metadata should populate the following fields:
      - Service Provider (SP) Entity ID - ACS URL
    3. 3.
      IDP Entity ID:
      Note the IDP Entity ID
      If you do not already have an IDP Entity ID, contact [email protected]​

2b: Configure the Service Provider Attribute Name Mapping

User Attributes: PixieBrix requires certain attributes to provision a user from your IDP. You must map attributes from your IDP to the Service Provider attributes PixieBrix requires.
SAML defines Attribute Definitions for configuring Service Provider attributes. For example, urn:oid:0.9.2342.19200300.100.1.3 corresponds to the user’s email.
PixieBrix requires the following attributes:
Service Provider Attribute Name
Identity Provider Attribute
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
Example: JumpCloud Configuration
Service Provider Attribute Name
JumpCloud 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
For example, once completed in JumpCloud, the “User Attributes” section should contain the following attribute name mapping:
Completed User Attribute Mapping in JumpCloud

Example: Microsoft Entra (formerly Azure AD)

Service Provider Attribute Name
Entra 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

2c: Assign Users in the Identity Provider to the SAML Application

Grant the users that should have access to log in with SAML.
For example: the screenshot below shows granting the PixieBrix Engineering group access to the SAML App in JumpCloud
​
image
​

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 IDPs 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. 1.
    Contact [email protected] to receive the authentication flow URL
  2. 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
Previous
Enabling Login with Microsoft
Next
Browser Extension Installation and Configuration
Last modified 14d ago