Mirrors/unleash.unleash
1
0
Fork 0
mirror of https://github.com/Unleash/unleash.git synced 2025-01-25 00:07:47 +01:00
Code Issues Projects Releases Wiki Activity

docs: Documented the environment variables available for configuring SSO (#7630)

Browse Source 
Co-authored-by: Gastón Fournier <gaston@getunleash.io>
This commit is contained in:
Christopher Kolstad 2024-07-22 12:02:11 +02:00 committed by GitHub
parent 0f0a680af3
commit 44192934f8
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
2 changed files with 132 additions and 23 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

41
website/docs/how-to/how-to-add-sso-open-id-connect.md
View File

@ -76,3 +76,44 @@ Log out of Unleash and sign back in again. You should now be presented with the
![Verify SSO](/img/sso-oidc-verify.png) ![Verify SSO](/img/sso-oidc-verify.png)
Success! Success!
## Configuration via Environment variables (Since Unleash Enterprise 6.1.0)
Beware, configuring OIDC through environment variables will disable editing settings in the Administration GUI. If you want to fallback to the GUI, make sure
the OIDC_ENABLED is not set and then restart Unleash.
### Step 1 Setup required variables for OIDC (minimal setup)
| Variable name | Purpose | Required | Example values |
|--------------------|-----------------------------------------------------------------------|----------|---------------------------------------------------------------|
| OIDC_ENABLED | Tells Unleash to use environment variables for configuring OIDC | yes | true / false (false will turn off OIDC login) |
| OIDC_DISCOVER_URL | URL used to dynamically retrieve the OIDC configuration | yes | https://myoidchost.azure.com/.well-known/openid-configuration |
| OIDC_CLIENT_ID | The OIDC client ID of this application. | yes | FB87266D-CDDB-4BCF-BB1F-8392FD0EDC1B |
| OIDC_CLIENT_SECRET | Shared secret from OpenID server. Used to authenticate login requests | yes | qjcVfeFjEfoYAF3AEsX2IMUWYuUzAbXO |
Once these are configured OIDC should be working.
### Step 2 (optional) - Auto create users from specific email domains
| Variable name | Purpose | Required | Example values |
|--------------------------------|------------------------------------------------------------------------------------------------|----------|-----------------------------|
| OIDC_AUTO_CREATE | Tells Unleash to auto create users from the specific domains in OIDC_AUTO_CREATE_EMAIL_DOMAINS | no | true / false |
| OIDC_AUTO_CREATE_EMAIL_DOMAINS | A comma separated list of domains to auto-create users for, if not set accepts all domains | no | getunleash.io,getunleash.ai |
### Step 3 (optional) Enable group syncing
| Variable name | Purpose | Required | Example values |
|-----------------------------|----------------------------------------------------------------------------------------------------------|------------|-----------------------------|
| --------------------------- | -------------------------------------------------------------------------------------------------------- | ---------- | ----------------- |
| OIDC_ENABLE_GROUP_SYNCING | Tell Unleash to setup group syncing from OIDC login requests (defaults to false) | No | true or false |
| OIDC_GROUP_JSON_PATH | a json path expression telling where in the response Unleash can find the group membership information | No | groups |
| OIDC_ADD_GROUPS_SCOPE | Tells Unleash to add the `groups` access scope to the request (defaults to false) | No | true / false |
| OIDC_DEFAULT_ROOT_ROLE | Which role to grant users auto created from SSO, defaults to Viewer | No | 'Viewer', 'Editor', 'Admin' |
### Step 4 (optional) - Further customizations
| Variable name | Purpose | Required | Example values |
|---------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------|---------------------|
| OIDC_ACR_VALUES | Authentication Context Class Reference, used to request extra values in the acr claim returned from the server. If multiple values are required, they should be space separated. | no |
| OIDC_ID_TOKEN_SIGNING_ALGORITHM | Only use this if your provider is failing with unsupported algorithm, the default should be fine here | No | RS256, RS384, RS512 |
| OIDC_ENABLE_SINGLE_SIGN_OUT | Should Unleash call the single signout of the OIDC endpoint (defaults to false) | No | true / false |

114
website/docs/how-to/how-to-add-sso-saml.md
View File

@ -4,32 +4,38 @@ title: How to add SSO with SAML 2.0 Okta
:::note Availability :::note Availability
The **Single-Sign-On capability** is only available for customers on the Enterprise subscription. Check out the [Unleash plans](https://www.getunleash.io/plans) for details. The **Single-Sign-On capability** is only available for customers on the Enterprise subscription. Check out
the [Unleash plans](https://www.getunleash.io/plans) for details.
::: :::
## Introduction {#introduction} ## Introduction {#introduction}
In this guide we will do a deep dive on the Single-Sign-On (SSO) integration with SAML 2.0 and connect it with Okta as IdP. Unleash support other identity providers and protocols, have a look at [all available Single-Sign-On options](../reference/sso.md) In this guide we will do a deep dive on the Single-Sign-On (SSO) integration with SAML 2.0 and connect it with Okta as
IdP. Unleash support other identity providers and protocols, have a look
at [all available Single-Sign-On options](../reference/sso.md)
## Basic configuration ## Basic configuration
### Step 1: Sign-in to Unleash {#step-1} ### Step 1: Sign-in to Unleash {#step-1}
In order to configure SSO you will need to log in to the Unleash instance with a user that have "Admin" role. If you are self-hosting Unleash then a default user will be automatically created the first time you start Unleash: In order to configure SSO you will need to log in to the Unleash instance with a user that have "Admin" role. If you are
self-hosting Unleash then a default user will be automatically created the first time you start Unleash:
- username: `admin` - username: `admin`
- password: `unleash4all` - password: `unleash4all`
### Step 2: Navigate to SSO configuration {#step-2} ### Step 2: Navigate to SSO configuration {#step-2}
In order to configure SSO with SAML with your Unleash enterprise you should navigate to the Single-Sign-On configuration section and choose the "SAML 2.0" tab. In order to configure SSO with SAML with your Unleash enterprise you should navigate to the Single-Sign-On configuration
section and choose the "SAML 2.0" tab.
![sso-config](/img/sso-configure-saml.png) ![sso-config](/img/sso-configure-saml.png)
### Step 3: Create an application in Okta {#step-3} ### Step 3: Create an application in Okta {#step-3}
Open a new tab/window in your browser and sign in to your Okta account. We will need to create a new Application which will hold the settings we need for Unleash. Open a new tab/window in your browser and sign in to your Okta account. We will need to create a new Application which
will hold the settings we need for Unleash.
**a) Navigate to “Admin -> Applications” and click the “Add Application” button.** **a) Navigate to “Admin -> Applications” and click the “Add Application” button.**
@ -41,9 +47,11 @@ Open a new tab/window in your browser and sign in to your Okta account. We will
**c) Configure SAML 2.0** **c) Configure SAML 2.0**
Unleash expects an email to be sent from the SSO provider so make sure Name ID format is set to email. Also you must give the IdP Initiated SSO URL Name, we have chosen to call it “unleash-enterprise”. This gives us the Sign-on URL we will need in our Unleash configuration later. Unleash expects an email to be sent from the SSO provider so make sure Name ID format is set to email. Also you must
give the IdP Initiated SSO URL Name, we have chosen to call it “unleash-enterprise”. This gives us the Sign-on URL we
will need in our Unleash configuration later.
In addition you may provide the following attributes: Additionally, you may provide the following attributes:
- firstName - firstName
- lastName - lastName
@ -52,7 +60,8 @@ _(These will be used to enrich the user data in Unleash)._
![Okta: Configure SAML](/img/okta_configure_saml2.0-768x832.png) ![Okta: Configure SAML](/img/okta_configure_saml2.0-768x832.png)
> Please make sure to replace URLs with the public URL for your Unleash instance. This will require correct region prefix and the instance name. The example above uses region="us" and instance-name="ushosted". > Please make sure to replace URLs with the public URL for your Unleash instance. This will require correct region
> prefix and the instance name. The example above uses region="us" and instance-name="ushosted".
> >
> The correct format is: https://**[region]**.app.unleash-hosted.com/**[instanceName]**/auth/saml/callback > The correct format is: https://**[region]**.app.unleash-hosted.com/**[instanceName]**/auth/saml/callback
@ -64,31 +73,41 @@ Click the “View Setup Instructions” to get the necessary configuration requi
### Step 4: Configure SAML 2.0 provider in Unleash {#step-4} ### Step 4: Configure SAML 2.0 provider in Unleash {#step-4}
Go back to Unleash Admin Dashboard and navigate to `Admin Menu -> Single-Sign-On -> SAML`. Fill in the values captured in the _"Get the Okta Setup Instructions"_ step. Go back to Unleash Admin Dashboard and navigate to `Admin Menu -> Single-Sign-On -> SAML`. Fill in the values captured
in the _"Get the Okta Setup Instructions"_ step.
You may also choose to “Auto-create users”. This will make Unleash automatically create new users on the fly the first time they sign-in to Unleash with the given SSO provider (JIT). If you decide to automatically create users in Unleash you must also provide a list of valid email domains. You must also decide which root Unleash role they will be assigned (Editor role will be the default). You may also choose to “Auto-create users”. This will make Unleash automatically create new users on the fly the first
time they sign-in to Unleash with the given SSO provider (JIT). If you decide to automatically create users in Unleash
you must also provide a list of valid email domains. You must also decide which root Unleash role they will be
assigned (Editor role will be the default).
![Unleash: SAML 2.0](/img/sso-saml-unleash.png) ![Unleash: SAML 2.0](/img/sso-saml-unleash.png)
### Step 5: Validate {#step-5} ### Step 5: Validate {#step-5}
You have now successfully configured Unleash to use SAML 2.0 together with Okta as an IdP. Please note that you also must assign users to the application defined in Okta to actually be able to log-in to Unleash. You have now successfully configured Unleash to use SAML 2.0 together with Okta as an IdP. Please note that you also
must assign users to the application defined in Okta to actually be able to log-in to Unleash.
Try signing out of Unleash. If everything is configured correctly you should be presented with the option to sign in with SAML 2.0. Try signing out of Unleash. If everything is configured correctly you should be presented with the option to sign in
with SAML 2.0.
## Single-Sign-Out ## Single-Sign-Out
> Available from `Unleash Enterprise 4.1.0` > Available from `Unleash Enterprise 4.1.0`
You may also configure Unleash to to perform Single-Sign-Out. By enabling single-sign-out Unleash will redirect the user back to IdP as part of the sign-out process. You may optionally also sign the sign-out request (required by multiple IdP's such as Okta). You may also configure Unleash to perform Single-Sign-Out. By enabling single-sign-out Unleash will redirect the user
back to IdP as part of the sign-out process. You may optionally also sign the sign-out request (required by multiple
IdP's such as Okta).
### Step 1: Generate private key & public certificate ### Step 1: Generate private key & public certificate
_(This step is only required if you intend to sign the sign-out requests)._ _(This step is only required if you intend to sign the sign-out requests)._
Before you can configure single-sign-out support with Okta you are required to generate a Private Key together with a public certificate for that key. We recommend to use SHA256 certificates. Before you can configure single-sign-out support with Okta you are required to generate a Private Key together with a
public certificate for that key. We recommend to use SHA256 certificates.
To create a public certificate and private key pair, use the proceeding commands. They work in Linux® and Mac® terminals. To create a public certificate and private key pair, use the proceeding commands. They work in Linux® and Mac®
terminals.
```bash ```bash
openssl genrsa -out private.pem 2048 openssl genrsa -out private.pem 2048
@ -102,7 +121,8 @@ Answer the promoted questions, and when you complete all the steps you should en
### Step 2: Configure sign-out url in Okta ### Step 2: Configure sign-out url in Okta
Login in to Okta and navigate to your Applications. Select the "Unleash" application you created, click on "General" and then "Edit SAML Settings". Login in to Okta and navigate to your Applications. Select the "Unleash" application you created, click on "General" and
then "Edit SAML Settings".
![SAML 2.0 Okta edit](/img/sso-saml-okta-edit.png) ![SAML 2.0 Okta edit](/img/sso-saml-okta-edit.png)
@ -112,11 +132,12 @@ Login in to Okta and navigate to your Applications. Select the "Unleash" applica
<br /><br /> <br /><br />
![SAML 2.0 Okta sing-out config](/img/sso-saml-okta-signout.png) ![SAML 2.0 Okta sign-out config](/img/sso-saml-okta-signout.png)
<br /><br /> <br /><br />
> Please make sure to replace URLs with the public URL for your Unleash instance. This will require correct region prefix and the instance name. The example above uses region="us" and instance-name="ushosted". > Please make sure to replace URLs with the public URL for your Unleash instance. This will require correct region
> prefix and the instance name. The example above uses region="us" and instance-name="ushosted".
> >
> The correct format is: https://**[region]**.app.unleash-hosted.com/**[instanceName]**/auth/saml/logout/done > The correct format is: https://**[region]**.app.unleash-hosted.com/**[instanceName]**/auth/saml/logout/done
@ -125,16 +146,63 @@ You need to fill out the following options:
- Single Logout Url: https://**[region]**.app.unleash-hosted.com/**[instanceName]**/auth/saml/logout/done - Single Logout Url: https://**[region]**.app.unleash-hosted.com/**[instanceName]**/auth/saml/logout/done
- SP Issuer: https://**[region]**.app.unleash-hosted.com/**[instanceName]** - SP Issuer: https://**[region]**.app.unleash-hosted.com/**[instanceName]**
Next upload the public Certificate you generated in the previous step (`cert.pem`) and save the Okta SAML settings. Upon completion of this step you should be provided with the ability to view setup instructions and now you should be provided with a "Identity Provider Single Logout URL" Next upload the public Certificate you generated in the previous step (`cert.pem`) and save the Okta SAML settings. Upon completion of this step you should be
provided with the ability to view setup instructions and now you should be provided with a "Identity Provider Single Logout URL"
![SAML 2.0 Okta sing-out url](/img/sso-saml-okta-signout-url.png) ![SAML 2.0 Okta sign-out url](/img/sso-saml-okta-signout-url.png)
### Step 3: Configure Single-Sign-Out in Unleash ### Step 3: Configure Single-Sign-Out in Unleash
Go back to Unleash Admin Dashboard and navigate to `Admin Menu -> Single-Sign-On -> SAML`. Fill in the values captured in the "Single Logout URL" from Okta. Go back to Unleash Admin Dashboard and navigate to `Admin Menu -> Single-Sign-On -> SAML`. Fill in the values captured in the "Single Logout URL" from Okta.
In the "Service Provide X.509 Certificate" field you should insert the value of your private key (`private-pem`). This is required in order to make Unleash able to sign logout requests. In the "Service Provide X.509 Certificate" field you should insert the value of your private key (`private-pem`). This is required in order to make Unleash able
to sign logout requests.
![SAML 2.0 Okta sing-out config](/img/sso-saml-okta-signout-unleash.png) ![SAML 2.0 Okta sign-out config](/img/sso-saml-okta-signout-unleash.png)
After you save these settings users will now be redirected to your IdP (Okta) and back to Unleash again after successfully signing out. After you save these settings users will now be redirected to your IdP (Okta) and back to Unleash again after
successfully signing out.
## Configuration via Environment variables (Since Unleash Enterprise 6.1.0)
Beware, configuring OIDC through environment variables will disable editing settings in the Administration GUI. If you want to fallback to the GUI, make sure
the SAML_ENABLED is not set and then restart Unleash. Your previous environment settings will have been persisted to the database and you can edit there.
### Step 1 - Setup required environment variables for SAML (minimal config)
Having SAML configured via environment variables allows you to start Unleash with SAML authentication preconfigured.
You'll need the following variables at the very least
| Variable name | Purpose | Required | Possible values |
|-----------------------|-----------------------------------------------------------------------------------------------------------|------------------------------------------|-------------------------|
| SAML_ENABLED | Tells unleash that you want to use environment variable configuration and turns on support for SAML login | Yes | true / false |
| SAML_ENTITY_ID | The SAML 2.0 entity ID | Yes | Strings |
| SAML_SIGNON_URL | Which URL to use for redirecting Single Sign on requests | Yes | Valid url |
| SAML_CERTIFICATE_FILE | An absolute path to read the X509 certificate from | Only if SAML_CERTIFICATE is not set | Absolute file paths |
| SAML_CERTIFICATE | The X509 certificate as a string | Only if SAML_CERTIFICATE_FILE is not set | X509 certificate string |
### Step 2 (optional) - Setup auto-creation of users from email domain
| Variable name | Purpose | Required | Possible values |
|--------------------|------------------------------------------------------------|----------|-----------------------------------------------------------------------------------|
| SAML_AUTO_CREATE | Tell Unleash to auto create users that sign in through SSO | No | true or false (though false is the same as not setting it at all. Defaults to false) |
| SAML_EMAIL_DOMAINS | These domains will have users auto created | No | Comma-separated list of email domains that you want Unleash to accept users from. |
### Step 3 (optional) - Add sign-out config
If you've read the [documentation for sign out config](link to chapter on sign out) above. You'll still need to create the SSL certificate, you can store it on
disk or pass in the contents of `private.pem` as a string. You'll need the following environment variables
| Variable name | Purpose | Required | Possible values |
|-------------------------------|-------------------------------------------------------------------------|----------------------------------------------------------------------------------|-----------------------------|
| SAML_SIGNOUT_URL | Single logout URL | No | Valid URL from SSO provider |
| SAML_SIGNOUT_CERTIFICATE_PATH | An absolute path to read the certificate to use to sign logout requests | Either this or SAML_SIGNOUT_CERTIFICATE must be set for Signout to work | Absolute file paths |
| SAML_SIGNOUT_CERTIFICATE | The private certificate created to sign logout requests | Either this or SAML_SIGNOUT_CERTIFICATE_PATH must be set for SSO signout to work | X509 certificate |
### Step 4 (optional) - Add group syncing
| Variable name | Purpose | Required | Possible values |
|---------------------------|--------------------------------------------------------------------------------------------------------|----------|-----------------|
| SAML_ENABLE_GROUP_SYNCING | Tell Unleash to setup group syncing from SAML login requests (defaults to false) | No | true or false |
| SAML_GROUP_JSON_PATH | a json path expression telling where in the response Unleash can find the group membership information | No | |