SAML

Configure Onyx with SAML authentication.

Enterprise Edition FeatureContact us to see if Enterprise Edition is right for you.

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

Create Okta Application

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

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.

Assign Users to Application

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

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

sp: entityId

sp: assertionConsumerService: url

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.

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

Getting Started

Deployment Guides

Authentication

Configuration

Miscellaneous

Guide

Getting Started

Deployment Guides

Authentication

Configuration

Miscellaneous

​Guide

Guide