SAML

SAML authentication setup

Configure Onyx with SAML authentication.

This guide will walk you through the setup process for Okta. Other identity providers will have a similar process. Please contact us if you need help with a different identity provider.

SAML authentication requires building Onyx images from source!

See details in the Docker Compose guide.

Guide

1. Create Okta Application

   Navigate to the Okta Admin Console → Applications → Create App Integration.

   
2. Configure Okta Application

   Select SAML 2.0.

   Name your application Onyx and upload the Onyx logo.

   If you are white-labeling Onyx, you can freely name your application and upload your own logo.

   Add a Sign sign-on URL

   https://YOUR_ONYX_DOMAIN.com/auth/saml/callback
   

   Add an Audience URI (SP Entity ID)

   https://YOUR_ONYX_DOMAIN.com/metadata
   

   Add an Attribute Statement where Name is email and Value is user.email.

   
3. Assign Users to Application

   Create the application and navigate to the Assignments tab to assign users.

4. Configure Onyx for SAML

   Navigate to onyx/backend/ee/onyx/configs/saml_config and copy the template settings file.

   cd onyx/backend/ee/onyx/configs/saml_config
   cp template_settings.yaml settings.yaml
   

   Edit the settings.yaml file with the following values:

   idp: entityId

   Go to the Sign On tab of your application in Okta, copy the Metadata URL, and paste it into your browser. You should see XML like:

   <md:EntityDescriptor
       xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata"
       entityID="http://www.okta.com/exkngircrvOYQyNg35d7">
   ...
   </md:EntityDescriptor>
   

   Copy the entityID value and paste it into idp: entityId in settings.yaml.

   idp: x509cert

   In the XML from the previous step, find the ds:X509Certificate element.

   <md:KeyDescriptor use="signing">
       <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
           <ds:X509Data>
               <ds:X509Certificate>
                   [Some certificate value here]
               </ds:X509Certificate>
           </ds:X509Data>
       </ds:KeyInfo>
   </md:KeyDescriptor>
   

   Copy the certificate value and paste it into idp: x509cert in settings.yaml.

   idp: singleSignOnService: url

   Go to the General tab of your application in Okta and copy the Embed Link.

   sp: entityId

   This is the same as the Audience URI (SP Entity ID) you added to the Okta application.

   https://YOUR_ONYX_DOMAIN.com/metadata
   

   sp: assertionConsumerService: url

   This is the same as the Sign sign-on URL you added to the Okta application.

   https://YOUR_ONYX_DOMAIN.com/auth/saml/callback
   

   sp: x509cert

   Generate a self-signed certificate:

   openssl genrsa -out sp-private-key.pem 2048
   openssl req -new -x509 -key sp-private-key.pem -out sp-cert.pem -days 730 -subj "/CN=<YOUR_DOMAIN e.g. saml.onyx.dev>"
   awk 'NF {sub(/\r/, ""); printf "%s\\n",$0;}' sp-cert.pem
   

   Copy the certificate value and paste it into sp: x509cert in settings.yaml.

5. Set Onyx Environment Variables

   Set the following environment variables in your .env or values.yaml file (Docker and Kubernetes, respectively).

   .env

   AUTH_TYPE=saml
   

   If you’re using Docker but don’t have a .env file, copy onyx/deployment/docker_compose/env.prod.template to a new .env file in the same directory.

   values.yaml

   configMap:
     AUTH_TYPE: saml