1
0
mirror of https://github.com/Unleash/unleash.git synced 2025-05-08 01:15:49 +02:00

Fix/sso docs (#931)

Update SSO docs to match capabilities introduced in 4.1.x release. 

Co-authored-by: Fredrik Oseberg <fredrik.no@gmail.com>
This commit is contained in:
Ivar Conradi Østhus 2021-09-02 11:19:02 +02:00 committed by GitHub
parent 5e5c1f3f7e
commit c3bd2acda3
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
19 changed files with 361 additions and 170 deletions

View File

@ -1,170 +0,0 @@
---
id: enterprise-authentication
title: Authentication (Single-Sign-On)
---
> This guide only applies to customers on the Enterprise subscription. Check out the [Unleash subscription plans](https://www.getunleash.io/plans) for details.
## Introduction {#introduction}
In this guide we will do a deep dive on the Single-Sign-On (SSO) integrations. Unleash Enterprise supports SAML 2.0, OpenID Connect and Google Authentication. In addition, Unleash Enterprise also supports username/password authentication out of the box, as you get with all the other versions of Unleash.
## Step 1: Sign-in {#step-1-sign-in}
In order to configure SSO Authentication 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`
- password: `unleash4all` (or `admin` if you started with Unleash v3).
## Step 2: Configure Authentication provider {#step-2-configure-authentication-provider}
Unleash enterprise supports multiple authentication providers, and we provide in depth guides for each of them. To find them navigate to "Admin" => "Authentication" section.
![admin-authentication](/img/admin-authentication.png)
## Step 3a: SAML 2.0 {#step-3a-saml-20}
### Okta with SAML 2.0 {#okta-with-saml-20}
If you are using Okta as your Authentication provider you start by signing in to your Okta account.
**Step 1: Create new Okta application**
Navigate to “Admin/Applications” and click the “Add Apps” button.
![Okta: Add Apps](/img/okta_add_application-768x345.png)
Then click “Create Application” and choose a new “SAML 2.0” application and click create
![Okta: Create Application](/img/okta_create_new_application-768x467.png)
**Step 2: Configure SAML**
Unleash expect 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.
![Okta: Configure SAML](/img/okta_configure_saml2.0-768x832.png)
> ### Important!
>
> Please make sure to replace URLs with the correct URL for your dedicated 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
**Step 3: Get Setup Instructions**
Click the “view Setup Instructions” to get the necessary configuration required for Unleash.
![Okta: Setup Instructions](/img/okta_setup-instructions-768x731.png)
**Step 4: Configure SAML 2.0 Authentication provider in Unleash**
Open Unleash Admin Dashboard and navigate to Admin -> Authentication -> SAML. Fill in the values captured in the “Get Setup Instructions” step.
You may also choose to “auto create users”. This will make Unleash automatically create new users on the fly first time they sign-in to Unleash with the given SSO provider. You may also limit the auto-creation to certain email domains, shown in the example below.
![Unleash: SAML 2.0](/img/saml-2.0-unleash.png)
**Success!**
That should be it. Please note that you also must assign users to the application defined in Okta to actually be able to log-in to Unleash.
### Keycloak with SAML 2.0 {#keycloak-with-saml-20}
**Step 1: Add client in Keycloak**
Open to the Keycloak dashboard and navigate to “Clients” and click “Add Client” button. Give it a unique clientId (e.g. unleash), use the “saml” protocol and specify the following SAML Endpoint:
```
https://<unleash.hostname.com>/auth/saml/callback
```
![Keycloak: Add client](/img/keykloak_step1-768x347.png)
**Step 2: Change “Name ID format to “email”** Unleash expect email to be sent from the SSO provider so make sure Name ID format is set to email, see a). also you must give the IDP Initiated SSO URL Name, we have chosen to call it “unleash”, see 2). This gives us the Sign-on URL we will need in our Unleash configuration later.
![Keycloak: step 2](/img/keykloak_step2b-768x242.png)
**Step 3: Copy the Keycloak Entity ID an Signing key**
Navigate to “Realm Settings” and open the “SAML 2.0 Identity Provider Metadata”. You will need copy the entityID (a) and the X509Certificate (B). These will be required when configuring SAML 2.0 in Unleash.
![Keycloak: step 3](/img/keykloak_step3-768x235.png)
**Step 4: Configure SAML 2.0 Authentication provider in Unleash**
Open Unleash Admin Dashboard and navigate to Admin -> Authentication. Fill in the values captured in the previous steps.
- Entity ID (3a)
- Single Sing-On URL (2b)
- Certificate (3b)
You may also choose to “auto create users”. This will make Unleash automatically create new users on the fly first time they sign-in to Unleash with the given SSO provider. You may also limit the auto-creation to certain email domains, shown in the example below.
![Keycloak: step 4](/img/keykloak_step4-768x644.png)
## Step 3b: OpenID Connect {#step-3b-openid-connect}
### Okta with OpenID Connect {#okta-with-openid-connect}
If you are using Okta as your Authentication provider you start by signing in to your Okta account.
**Step 1: Create new Okta application**
Navigate to “Admin/Applications” and click the “Add Apps” button.
![Okta: Add Apps](/img/okta_add_application-768x345.png)
Then click “Create Application” and choose a new “OIDC - OpenID Connect” application, and choose application type "Web Application" and click create.
![Okta: Create Apps](/img/okta-oidc-create.png)
**Step 2: Configure Application Integration**
Give you application a name. And set the Sign-in redirect URI to:
`https://[unleash.hostname.some]/auth/oidc/callback`
![Okta: Configure OpenID Connect](/img/okta-oidc-configure.png)
Save your new application and your will ge the required details you need to configure the Unleash side of things:
![Okta: Configure OpenID Connect](/img/okta-oidc-details.png)
**Step 3: Configure OpenID Connect provider in Unleash**
Navigate to Unleash and insert the details (Discover URL, Client Id and Client Secret) in to Unleash.
![Unleash: Configure OpenID Connect](/img/oidc-unleash.png)
## Step 3c: Google Authentication {#step-3c-google-authentication}
**Step 1: Setup Google OAuth 2.0 Credentials** Go to https://console.developers.google.com/apis/credentials
1. Click “Create credentials“
2. Choose “Oauth Client Id”
3. Choose Application Type: web application
4. Add https://[unleash.hostname.com]/auth/google/callback as an authorized redirect URI.
You will then get a Client ID and a Client Secret that you will need in the next step.
![Google OAuth: Secret](/img/sso-google-secret.png)
**Step 2: Configure Unleash**
Login to Unleash (admin/admin) and navigate to Admin -> Authentication -> Google.
First insert the Client Id and Client Secret from step 1.
You must also specify the hostname Unleash is running on. If Unleash is running on localhost you should specify the port as well (localhost:4242).
If you want to allow everyone to access Unleash, and have Unleash auto-create users you can enable this option. You should then also specify which email domains you want to allow logging in to Unleash.
Remember to click “Save” to store your settings.
![Google OAuth: Secret](/img/google_auth_settings.png)
## Step 4: Verify {#step-4-verify}
Logout of Unleash and sign back in again. You should now be presented with the “SSO Authentication Option”. Click the button and follow the sign-in flow. If all goes well you should be successfully signed in to Unleash. If something is not working you can still sign-in with username and password.
![Verify SSO](/img/sign-in.png)

View File

@ -0,0 +1,58 @@
---
id: sso-google
title: SSO - Google (deprecated)
---
> Single Sign-on via the Google Authenticator provider is deprecated. We recommend using [OpenId Connect](./sso-open-id-connect.md) instead.
## Introduction {#introduction}
In this guide we will do a deep dive on the Single-Sign-On (SSO) using Google Authentication. Unleash supports other identity providers and protocols, have a look at [all available Single-Sign-On options](./sso.md)
## Basic configuration
### 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:
- username: `admin`
- password: `unleash4all`
### Step 2: Navigate to SSO configuration {#step-2}
In order to configure SSO with Google with your Unleash enterprise you should navigate to the Single-Sign-On configuration section and choose the "Google" tab.
![sso-config](/img/sso-configure.png)
### Step 3: Google Authentication {#step-3n}
Navigate to https://console.developers.google.com/apis/credentials
1. Click `Create credentials`
2. Choose `Oauth Client Id`
3. Choose Application Type: `web application`
4. Add https://[unleash.hostname.com]/auth/google/callback as an authorized redirect URI.
You will then get a `Client ID` and a `Client Secret` that you will need in the next step.
![Google OAuth: Secret](/img/sso-google-secret.png)
### Step 4: Configure Unleash {#step-4}
Login to Unleash and navigate to `Admin menu -> Single-Sign-on -> Google`.
First insert the Client Id and Client Secret from step 3.
You must also specify the hostname Unleash is running on. If Unleash is running on localhost you should specify the port as well (localhost:4242).
If you want to allow everyone in your organization to access Unleash, and have Unleash auto-create users you can enable this option. You should then also specify which email domains you want to allow logging in to Unleash.
Remember to click “Save” to store your settings.
![Google OAuth: Secret](/img/google_auth_settings.png)
### Step 5: Verify {#step-5}
Logout of Unleash and sign back in again. You should now be presented with the “SSO Authentication Option”. Click the button and follow the sign-in flow. If all goes well you should be successfully signed in to Unleash. If something is not working you can still sign-in with username and password.
![Verify SSO](/img/sign-in-google.png)

View File

@ -0,0 +1,75 @@
---
id: sso-open-id-connect
title: SSO - OpenId Connect
---
> 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}
In this guide we will do a deep dive on the Single-Sign-On (SSO) using the OpenID Connect protocol and connect it with Okta as IdP. Unleash supports other identity providers and protocols, have a look at [all available Single-Sign-On options](./sso.md)
## Basic configuration
### 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:
- username: `admin`
- password: `unleash4all`
### Step 2: Navigate to SSO configuration {#step-2}
Unleash enterprise supports multiple authentication providers, and we provide in depth guides for each of them. To find them navigate to "Admin" => "Single-Sign-On" section.
![admin-authentication](/img/sso-oidc.png)
### Step 3: Okta with OpenID Connect {#step3}
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) Create new Okta application**
Navigate to “Admin/Applications” and click the “Add Apps” button.
![Okta: Add Apps](/img/okta_add_application-768x345.png)
Then click “Create Application” and choose a new “OIDC - OpenID Connect” application, and choose application type "Web Application" and click create.
![Okta: Create Apps](/img/okta-oidc-create.png)
**b) Configure Application Integration**
Give you application a name. And set the Sign-in redirect URI to:
`https://[region].app.unleash-hosted.com/[instanceName]/auth/oidc/callback`
(In a self-hosted scenario the URL must match your `UNLEASH_URL` configuration)
You can also configure the optional Sign-out redirect URIs: `https://[region].app.unleash-hosted.com/[instanceName]/`
![Okta: Configure OpenID Connect](/img/sso-oidc-okta.png)
Save your new application and your will ge the required details you need to configure the Unleash side of things:
![Okta: Configure OpenID Connect](/img/okta-oidc-details.png)
**c) Configure OpenID Connect provider in Unleash**
Navigate to Unleash and insert the details (Discover URL, Client Id and Client Secret) in to Unleash.
> Pleas note that the `Discover URL` must be a valid URL and must include the `https://` prefix. For example: **https://dev-example-okta.com** is a valid discovery URL.
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 global Unleash role they will be assigned (Editor role will be the default).
![Unleash: Configure OpenID Connect](/img/sso-oidc-unleash.png)
### Step 4: Verify {#step-4}
Logout of Unleash and sign back in again. You should now be presented with the "Sign in with OpenID Connect" option. Click the button and follow the sign-in flow. If all goes well you should be successfully signed in to Unleash.
(If something is not working you can still sign-in with username and password).
![Verify SSO](/img/sso-oidc-verify.png)
Success!

View File

@ -0,0 +1,63 @@
---
id: sso-saml-keycloak
title: SSO - SAML 2.0 Keycloak
---
> 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}
In this guide we will do a deep dive on the Single-Sign-On (SSO) integration with SAML 2.0 and connect it with Keycloak as IdP. Unleash supports other identity providers and protocols, have a look at [all available Single-Sign-On options](./sso.md)
## Basic configuration
### 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:
- username: `admin`
- password: `unleash4all`
### 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.
![sso-config](/img/sso-configure-saml.png)
### Step 3: Keycloak with SAML 2.0 {#step-3}
Open to the Keycloak dashboard and navigate to “Clients” and click “Add Client” button. Give it a unique clientId (e.g. unleash), use the “saml” protocol and specify the following SAML Endpoint:
```
https://<unleash.hostname.com>/auth/saml/callback
```
![Keycloak: Add client](/img/keykloak_step1-768x347.png)
**a) Change “Name ID format to “email”** Unleash expects an email to be sent from the SSO provider so make sure Name ID format is set to email, see a). also you must give the IDP Initiated SSO URL Name, we have chosen to call it “unleash”, see 2). This gives us the Sign-on URL we will need in our Unleash configuration later.
![Keycloak: step 2](/img/keykloak_step2b-768x242.png)
**b) Copy the Keycloak Entity ID an Signing key**
Navigate to “Realm Settings” and open the “SAML 2.0 Identity Provider Metadata”. You will need copy the entityID (a) and the X509Certificate (B). These will be required when configuring SAML 2.0 in Unleash.
![Keycloak: step 3](/img/keykloak_step3-768x235.png)
### Step 4: Configure SAML 2.0 Authentication provider in Unleash {#step-3}
Go back to Unleash Admin Dashboard and navigate to `Admin Menu -> Single-Sign-On -> SAML`. Fill in the values captured in the step 3.
- Entity ID (3b a)
- Single Sing-On URL (3a b)
- Certificate (3b b)
You may also choose to “auto create users”. This will make Unleash automatically create new users on the fly first time they sign-in to Unleash with the given SSO provider. You may also limit the auto-creation to certain email domains, shown in the example below.
![Keycloak: step 4](/img/keykloak_step4-768x644.png)
### Step 5: Validate {#step-5}
You have now successfully configured Unleash to use SAML 2.0 together with Keycloak as an IdP. Please note that you also must assign users to the application defined in Keycloak 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.

View File

@ -0,0 +1,137 @@
---
id: sso-saml
title: SSO - SAML 2.0 Okta
---
> 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}
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](./sso.md)
## Basic configuration
### 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:
- username: `admin`
- password: `unleash4all`
### 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.
![sso-config](/img/sso-configure-saml.png)
### 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.
**a) Navigate to “Admin -> Applications” and click the “Add Application” button.**
![Okta: Add Apps](/img/okta_add_application-768x345.png)
**b) Click “Create New App and choose a new “SAML 2.0” application and _click create_**
![Okta: Create Application](/img/okta_create_new_application-768x467.png)
**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.
In addition you may provide the following attributes:
- firstName
- lastName
_(These will be used to enrich the user data in Unleash)._
![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".
>
> The correct format is: https://**[region]**.app.unleash-hosted.com/**[instanceName]**/auth/saml/callback
**d) Get the Okta Setup Instructions**
Click the “View Setup Instructions” to get the necessary configuration required for Unleash.
![Okta: Setup Instructions](/img/okta_setup-instructions-768x731.png)
### 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.
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 global Unleash role they will be assigned (Editor role will be the default).
![Unleash: SAML 2.0](/img/sso-saml-unleash.png)
### 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.
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
> 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).
### Step 1: Generate private key & public certificate
_(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.
To create a public certificate and private key pair, use the proceeding commands. They work in Linux® and Mac® terminals.
```bash
openssl genrsa -out private.pem 2048
openssl req -new -x509 -sha256 -key private.pem -out cert.pem -days 1095
```
Answer the promoted questions, and when you complete all the steps you should end up with two files:
- `private.pem` - Private certificate, required by Unleash in order to sign requests.
- `cert.pem` - Public certificate, required by the IdP in order to validate requests from Unleash.
### 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".
![SAML 2.0 Okta edit](/img/sso-saml-okta-edit.png)
<br /><br />
**Next, navigate to "Configure SAML" and click "show Advanced Settings" and check the `Enable Single Logout` option. **
<br /><br />
![SAML 2.0 Okta sing-out config](/img/sso-saml-okta-signout.png)
<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".
>
> The correct format is: https://**[region]**.app.unleash-hosted.com/**[instanceName]**/auth/saml/logout/done
You need to fill out the following options:
- Single Logout Url: https://**[region]**.app.unleash-hosted.com/**[instanceName]**/auth/saml/logout/done
- 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"
![SAML 2.0 Okta sing-out url](/img/sso-saml-okta-signout-url.png)
### Step 3: Configure Single-Sign-Out in Unlash
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.
![SAML 2.0 Okta sing-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.

View File

@ -0,0 +1,24 @@
---
id: enterprise-authentication
title: Single-Sign-On
---
> 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.
Unleash Enterprise supports SAML 2.0, OpenID Connect and Google Authentication. In addition, Unleash supports username/password authentication out of the box.
### Before you start
In order to configure Single-Sign-On 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`
- password: `unleash4all` _(or `admin` if you started with Unleash v3)._
## Guides
Unleash enterprise supports multiple authentication providers.
- [OpenID Connect with Okta](./sso-open-id-connect.md)
- [SAML 2.0 with Okta](./sso-saml.md)
- [SAML 2.0 with Keycloak](./sso-saml-keycloak.md)
- [Google Authentication](./sso-google.md) (deprecated)

View File

@ -59,6 +59,10 @@ module.exports = {
'advanced/api_access',
'advanced/tags',
'advanced/enterprise-authentication',
'advanced/sso-saml-keycloak',
'advanced/sso-saml',
'advanced/sso-open-id-connect',
'advanced/sso-google',
],
},
api: {

Binary file not shown.

After

Width:  |  Height:  |  Size: 236 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 86 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 30 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 81 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 112 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 47 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 36 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 58 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 55 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 32 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 26 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 120 KiB