Skip to main content
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.Okta Create Integration Page
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.Okta Configure SAML Application Page
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:
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.
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.
Go to the General tab of your application in Okta and copy the Embed Link.
This is the same as the Audience URI (SP Entity ID) you added to the Okta application.
https://YOUR_ONYX_DOMAIN.com/metadata
This is the same as the Sign sign-on URL you added to the Okta application.
https://YOUR_ONYX_DOMAIN.com/auth/saml/callback
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