SAML - Gorbit Documentation

Configure Gorbit 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 Gorbit 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 Gorbit and upload the Gorbit logo.

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

Add a Sign sign-on URL

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

Add an Audience URI (SP Entity ID)

https://YOUR_GORBIT_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 Gorbit for SAML

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

cd gorbit/backend/ee/gorbit/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_GORBIT_DOMAIN.com/metadata

sp: assertionConsumerService: url

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

https://YOUR_GORBIT_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.gorbit.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 Gorbit 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 gorbit/deployment/docker_compose/env.prod.template to a new .env file in the same directory.

values.yaml

configMap:
  AUTH_TYPE: saml

​Guide

Guide