SAML

Configure Nexus with SAML authentication.

SAML providers are managed at Admin Panel → Organization → SSO Providers. No configuration files or restarts are needed, and you can configure multiple providers (enabling more than one at the same time requires the Business plan, see Plan Availability). SAML works on the standard Nexus images.

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

Guide#

Create Okta Application#

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

Configure Okta Application#

Select SAML 2.0.

Name your application Nexus and upload the Nexus logo.

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

Add a Single sign-on URL (the ACS URL, shared by every SAML provider on the instance):

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

Add an Audience URI (SP Entity ID). Any stable identifier works, as long as it matches the SP entity ID you enter in Nexus:

  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.

Collect the IdP Values#

Nexus needs three values from Okta:

IdP Entity ID#

  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.

IdP x509 Certificate#

  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.

IdP SSO URL#

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

Add the Provider in Nexus#

Navigate to Admin Panel → Organization → SSO Providers and click Add Provider.

Select the SAML provider type, give the provider a Name (a lowercase slug, e.g. okta), and paste the IdP entity ID, IdP SSO URL, IdP x509 certificate, and the SP entity ID from the Okta application.

Optional: SP certificate and private key#

If your IdP requires signed requests,
generate a self-signed certificate and enter both values in the provider form:

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

After creating the provider, its row shows the exact ACS URL. Confirm it matches the single sign-on URL you registered in Okta, then sign in through the new option on the login page.

Upgrading from v4.3 or Earlier#

Versions before v4.4.0 configured a single SAML provider through a settings.json file placed in the SAML config directory (SAML_CONF_DIR, default /app/onyx/configs/saml_config), with AUTH_TYPE=saml set. That flow uses the same ACS URL as above. On v4.4.0 and later this configuration no longer enables SAML login, and AUTH_TYPE is planned for full removal in v4.5. New installs must use the admin panel flow above.

When you upgrade an existing deployment, its settings.json is imported as an SSO provider entry automatically when the upgraded api server starts, and existing logins keep working. Keep the settings file mounted and AUTH_TYPE=saml set through the upgrade (the import reads both). The migrated provider keeps using the ACS URL already registered with your IdP, so nothing changes on the IdP side. Remove both after the provider appears in the admin panel.