Configure GiiS 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.

WARNING

SAML authentication requires building GiiS 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 `GiiS` and upload the GiiS logo.

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

:::

Add a **Sign sign-on URL**

  ```
  https://YOUR_GIIS_DOMAIN.com/auth/saml/callback
  ```

Add an **Audience URI (SP Entity ID)**

  ```
  https://YOUR_GIIS_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 GiiS for SAML

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

  ```bash
  cd giis/backend/ee/giis/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:

    ```XML
    <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.

    ```XML
    <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_GIIS_DOMAIN.com/metadata
    ```

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

    ```
    https://YOUR_GIIS_DOMAIN.com/auth/saml/callback
    ```

    Generate a self-signed certificate:

    ```bash
    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="
    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 GiiS Environment Variables

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

  ```bash .env
  AUTH_TYPE=saml
  ```

::: info
  If you're using Docker but don't have a `.env` file,
  copy `giis/deployment/docker_compose/env.prod.template` to a new `.env` file in the same directory.

:::

  ```bash values.yaml
  configMap:
    AUTH_TYPE: saml
  ```