diff --git a/docs/docs/authenticate/README.mdx b/docs/docs/authenticate/README.mdx index 79be62f38..46d5be19c 100644 --- a/docs/docs/authenticate/README.mdx +++ b/docs/docs/authenticate/README.mdx @@ -23,6 +23,8 @@ identity providers using our Generic OIDC integration: * [Azure Active Directory](oidc/azuread) * [Google](oidc/google) * [Onelogin](oidc/onelogin) +* [JumpCloud](saml/jumpcloud) +* [Keycloak](oidc/keycloak) * [Zitadel](oidc/zitadel) * [Auth0](oidc/auth0) diff --git a/docs/docs/authenticate/saml/README.mdx b/docs/docs/authenticate/saml/README.mdx index 5ec8c2350..fb3804805 100644 --- a/docs/docs/authenticate/saml/README.mdx +++ b/docs/docs/authenticate/saml/README.mdx @@ -10,11 +10,12 @@ Firezone supports Single Sign-On (SSO) via SAML 2.0. In general, most identity providers that support SAML 2.0 should work with Firezone. -| Provider | Support Status | Notes | -| --- | --- | --- | -| [Okta](okta) | **Tested and supported** | | -| [Onelogin](onelogin) | **Tested and supported** | | -| [Jumpcloud](jumpcloud) | **Tested and supported** | Uncheck `Require signed envelopes` | +| Provider | Support Status | Notes | +| --- | --- | --- | +| [Okta](okta) | **Tested and supported** | | +| [Google Workspace](google) | **Tested and supported** | Uncheck `Require signed envelopes` | +| [OneLogin](onelogin) | **Tested and supported** | | +| [JumpCloud](jumpcloud) | **Tested and supported** | Uncheck `Require signed envelopes` | Occasionally, providers that don't implement the full SAML 2.0 standard or use uncommon configurations may be problematic. If this is the case, [contact us]( diff --git a/docs/docs/authenticate/saml/google.mdx b/docs/docs/authenticate/saml/google.mdx new file mode 100644 index 000000000..a88921fd6 --- /dev/null +++ b/docs/docs/authenticate/saml/google.mdx @@ -0,0 +1,53 @@ +--- +title: Google Workspace +sidebar_position: 2 +description: Firezone's WireGuard®-based remote access platform supports using Google as a single sign-on provider using a SAML 2.0 connector. +--- + +:::note +This guide assumes you have completed the prerequisite steps +(e.g. generate self-signed X.509 certificates) outlined [here](/authenticate/saml#prerequisites). +::: + +Firezone supports Single Sign-On (SSO) using Google through the generic SAML 2.0 +connector. This guide will walk you through how to configure the integration. + +## Create a SAML connector + +In the Google Workspace admin portal, create a new SAML app under +the Application > Web and mobile apps tab. Use the following config values during setup: + +| Setting | Value | +|-----------------|------------------------------------------------------------------------------------------------------------------------------------------| +| App name | Firezone | +| App icon | [save link as](https://user-images.githubusercontent.com/52545545/202567638-513dba14-ea8c-4da8-8f75-341310f1e456.png) | +| ACS URL | This is your Firezone `EXTERNAL_URL/auth/saml/sp/consume/:config_id` (e.g., `https://firezone.company.com/auth/saml/sp/consume/google`). | +| Entity ID | This should be the same as your Firezone `SAML_ENTITY_ID`, defaults to `urn:firezone.dev:firezone-app`. | +| Signed response | Checked. | +| Name ID format | Unspecified | +| Name ID | Basic Information > Primary email | + +![Google SAML](https://user-images.githubusercontent.com/52545545/202566493-43cfc9c6-3d7f-4636-9cd9-a1a94187491c.png) + +Once complete, save the changes and download the SAML metadata document. You'll need +to copy-paste the contents of this document into the Firezone portal in the next step. + +## Add SAML identity provider to Firezone + +In the Firezone portal, add a SAML identity provider under the Security tab +by filling out the following information: + +| Setting | Value | Notes | +|---------------------------|----------------|----------------------------------------------------------------------------------------------------------------------------------------| +| Config ID | google | Firezone uses this value to construct endpoints required in the SAML authentication flow (e.g., receiving assertions, login requests). | +| Label | Google | Appears on the sign in button for authentication. | +| Metadata | see note | Paste the contents of the SAML metadata document you downloaded in the previous step from Google. | +| Sign assertions | Checked. | | +| Sign metadata | Checked. | | +| Require signed assertions | Checked. | | +| Required signed envelopes | **Unchecked.** | | + +![Firezone SAML](https://user-images.githubusercontent.com/52545545/202566502-3a06694b-249e-4330-9f6b-39004eb36406.png) + +After saving the SAML config, you should see a `Sign in with Google` button +on your Firezone portal sign-in page. diff --git a/docs/docs/authenticate/saml/jumpcloud.mdx b/docs/docs/authenticate/saml/jumpcloud.mdx index ffc78f506..71a2c44d1 100644 --- a/docs/docs/authenticate/saml/jumpcloud.mdx +++ b/docs/docs/authenticate/saml/jumpcloud.mdx @@ -1,19 +1,20 @@ --- -title: Jumpcloud -sidebar_position: 2 -description: Firezone's WireGuard®-based remote access platform supports using Jumpcloud as a single sign-on provider using a SAML 2.0 connector. +title: JumpCloud +sidebar_position: 4 +description: Firezone's WireGuard®-based remote access platform supports using JumpCloud as a single sign-on provider using a SAML 2.0 connector. --- :::note -This guide assumes you have completed the prerequisite steps outlined [here](/authenticate/saml). +This guide assumes you have completed the prerequisite steps +(e.g. generate self-signed X.509 certificates) outlined [here](/authenticate/saml#prerequisites). ::: -Firezone supports Single Sign-On (SSO) using Jumpcloud through the generic SAML 2.0 connector. +Firezone supports Single Sign-On (SSO) using JumpCloud through the generic SAML 2.0 connector. This guide will walk you through how to configure the integration. ## Create a SAML connector -In the Jumpcloud admin portal, create a new App under +In the JumpCloud admin portal, create a new App under the SSO tab. At the bottom of the popup window, click `Custom SAML App`. After entering your desired value for `Display Label`, click the `SSO` tab, @@ -28,12 +29,13 @@ then use the following configuration values: | SAMLSubject NameID Format | Leave at the default. | | Signature Algorithm | `RSA-SHA256` | | Sign Assertion | **Checked**. | +| Login URL | This is your Firezone `EXTERNAL_URL/auth/saml/auth/signin/:config_id`, e.g. `https://firezone.company.com/auth/saml/auth/signin/jumpcloud`| Leave the rest of the settings unchanged, then click the `activate` button at the bottom-right. -Your Jumpcloud configuration should now resemble the following: +Your JumpCloud configuration should now resemble the following: -![Jumpcloud SAML](https://user-images.githubusercontent.com/167144/202085625-41a818d4-bc9d-4f77-b2db-43656fa42804.png) +![JumpCloud SAML](https://user-images.githubusercontent.com/52545545/202558446-128e7484-eda6-429f-b6c1-dbabbf5dc7e3.png) Now, download the IdP Metadata document by selecting the App you just created and then clicking the `export metadata` button in the upper-right. You'll need @@ -47,9 +49,9 @@ by filling out the following information: | Setting | Value | Notes | | --- | --- | --- | | Config ID | `jumpcloud` | Firezone uses this value to construct endpoints required in the SAML authentication flow (e.g., receiving assertions, login requests). | -| Label | `Jumpcloud` | Appears on the sign in button for authentication. | +| Label | `JumpCloud` | Appears on the sign in button for authentication. | | Base URL | Leave unchanged. | | -| Metadata | see note | Copy-paste the contents of the SAML metadata document you downloaded in the previous step from Jumpcloud. | +| Metadata | see note | Copy-paste the contents of the SAML metadata document you downloaded in the previous step from JumpCloud. | | Sign assertions | Checked. | | | Sign metadata | Checked. | | | Require signed assertions | Checked. | | @@ -57,7 +59,7 @@ by filling out the following information: Your Firezone configuration should now resemble the following: -![Firezone SAML](https://user-images.githubusercontent.com/167144/202086477-50927200-4315-4c65-865a-33da6157af1b.png) +![Firezone SAML](https://user-images.githubusercontent.com/52545545/202557853-95246d0e-074c-4d31-ab89-26a3a3a7deda.png) -After saving the SAML config, you should see a `Sign in with Jumpcloud` button +After saving the SAML config, you should see a `Sign in with JumpCloud` button on your Firezone portal sign-in page. diff --git a/docs/docs/authenticate/saml/okta.mdx b/docs/docs/authenticate/saml/okta.mdx index e2da8182f..32f02dcfb 100644 --- a/docs/docs/authenticate/saml/okta.mdx +++ b/docs/docs/authenticate/saml/okta.mdx @@ -6,7 +6,7 @@ description: Firezone's WireGuard®-based remote access platform supports using :::note This guide assumes you have completed the prerequisite steps -outlined [here](/authenticate/saml). +(e.g. generate self-signed X.509 certificates) outlined [here](/authenticate/saml#prerequisites). ::: Firezone supports Single Sign-On (SSO) using Okta through the generic SAML 2.0 connector. This guide will walk you through how to configure the integration. @@ -17,32 +17,41 @@ In the Okta admin portal, create a new app integration under the Application tab. Select `SAML 2.0` as the authentication method. Use the following config values during setup: -| Setting | Value | -|--- |--- | -| App name | `Firezone` | -| App logo | [save link as](https://user-images.githubusercontent.com/52545545/155907625-a4f6c8c2-3952-488d-b244-3c37400846cf.png) | -| Single sign on URL | `https://firezone.company.com/auth/saml/sp/consume/okta` | -| Audience (EntityID) | `urn:firezone.dev:firezone-app` | -| Name ID format | `EmailAddress` | -| Application username | `Email` | -| Update application username on | `Create and update` | +| Setting | Value | +|--------------------------------|---------------------------------------------------------------------------------------------------------------------------------------| +| App name | Firezone | +| App logo | [save link as](https://user-images.githubusercontent.com/52545545/155907625-a4f6c8c2-3952-488d-b244-3c37400846cf.png) | +| Single sign on URL | This is your Firezone `EXTERNAL_URL/auth/saml/sp/consume/:config_id` (e.g., `https://firezone.company.com/auth/saml/sp/consume/okta`).| +| Audience (EntityID) | This should be the same as your Firezone `SAML_ENTITY_ID`, defaults to `urn:firezone.dev:firezone-app`. | +| Name ID format | EmailAddress | +| Application username | Email | +| Update application username on | Create and update | [Okta's documentation](https://help.okta.com/oie/en-us/Content/Topics/Apps/Apps_App_Integration_Wizard_SAML.htm) -contains additional details on the purpose of each configuration setting. In all -the fields above, replace `firezone.company.com` with your deployment's external URL. +contains additional details on the purpose of each configuration setting. + +![Okta SAML](https://user-images.githubusercontent.com/52545545/202565311-e98729cf-c7aa-4f8d-965a-55b076177add.png) + +After creating the SAML connector, visit the `View SAML setup instructions` link in +the Sign On tab to download the metadata document. You'll need +to copy-paste the contents of this document into the Firezone portal in the next step. ## Add SAML identity provider to Firezone In the Firezone portal, add a SAML identity provider under the Security tab by filling out the following information: -| Setting | Value | Notes | -|--- |--- |--- | -| Config ID | `Okta` | Firezone uses this value to construct endpoints required in the SAML authentication flow (e.g., receiving assertions, login requests).| -| Label | `Okta` | Appears on the sign in button for authentication. | -| Metadata | see note | Upload the contents of the SAML metadata document you downloaded in the previous step from Okta. | +| Setting | Value | Notes | +|---------------------------|----------|--------------------------------------------------------------------------------------------------------------------| +| Config ID | Okta | Used to construct endpoints required in the SAML authentication flow (e.g., receiving assertions, login requests). | +| Label | Okta | Appears on the sign in button for authentication. | +| Metadata | see note | Paste the contents of the SAML metadata document you downloaded in the previous step from Okta. | +| Sign assertions | Checked. | | +| Sign metadata | Checked. | | +| Require signed assertions | Checked. | | +| Required signed envelopes | Checked. | | -![Okta SAML](https://user-images.githubusercontent.com/52545545/201447060-e29f46d5-8511-4bdd-9a6e-2c3a38d19de9.png) +![Firezone SAML](https://user-images.githubusercontent.com/52545545/202557861-f7a85df0-d44f-48fd-a980-89e8b0c91503.png) After saving the SAML config, you should see a `Sign in with Okta` button on your Firezone portal sign-in page. diff --git a/docs/docs/authenticate/saml/onelogin.mdx b/docs/docs/authenticate/saml/onelogin.mdx index 56c63eb5a..b70a8235a 100644 --- a/docs/docs/authenticate/saml/onelogin.mdx +++ b/docs/docs/authenticate/saml/onelogin.mdx @@ -1,15 +1,16 @@ --- title: OneLogin -sidebar_position: 2 +sidebar_position: 3 description: Firezone's WireGuard based remote access platform supports using OneLogin as a single sign-on provider using a SAML 2.0 connector. --- :::note This guide assumes you have completed the prerequisite steps -outlined [here](/authenticate/saml). +(e.g. generate self-signed X.509 certificates) outlined [here](/authenticate/saml#prerequisites). ::: -Firezone supports Single Sign-On (SSO) using OneLogin through the generic SAML 2.0 connector. This guide will walk you through how to configure the integration. +Firezone supports Single Sign-On (SSO) using OneLogin through the generic SAML 2.0 connector. +This guide will walk you through how to configure the integration. ## Create a SAML connector @@ -19,35 +20,42 @@ configuration settings under the under the configuration tab. The following fields should be filled out on this page: -| Setting | Value | -|--- |--- | -| Audience (EntityID) | `urn:firezone.dev:firezone-app` | -| Recipient | `https://firezone.company.com/auth/saml/sp/consume/onelogin` | -| ACS URL Validator | `^https:\/\/firezone\.company\.com\/auth\/saml\/sp\/consume\/onelogin` | -| ACS URL | `https://firezone.company.com/auth/saml/sp/consume/onelogin` | -| Login URL | `https://firezone.company.com/auth/saml/auth/signin/onelogin` | -| SAML initiator | `Service Provider` | -| SAML signature element | `Both` | +| Setting | Value | +|------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Audience (EntityID) | This should be the same as your Firezone `SAML_ENTITY_ID`, defaults to `urn:firezone.dev:firezone-app`. | +| Recipient | This is your Firezone `EXTERNAL_URL/auth/saml/sp/consume/:config_id` (e.g., `https://firezone.company.com/auth/saml/sp/consume/onelogin`). | +| ACS URL Validator | This field is regex to ensure OneLogin posts the response to the correct URL. For the sample URL below, we can use `^https:\/\/firezone\.company\.com\/auth\/saml\/sp\/consume\/onelogin` | +| ACS URL | This is your Firezone `EXTERNAL_URL/auth/saml/sp/consume/:config_id` (e.g., `https://firezone.company.com/auth/saml/sp/consume/onelogin`). | +| Login URL | This is your Firezone `EXTERNAL_URL/auth/saml/auth/signin/:config_id` (e.g., `https://firezone.company.com/auth/saml/sp/consume/onelogin`). | +| SAML initiator | Service Provider | +| SAML signature element | Both | +| Encrypt Assertion | Checked. | [OneLogin's docs](https://onelogin.service-now.com/support?id=kb_article&sys_id=912bb23edbde7810fe39dde7489619de&kb_category=93e869b0db185340d5505eea4b961934) -provide a good overview of each field's purpose. In all the fields above, replace `firezone.company.com` -with your deployment's external URL. +provide a good overview of each field's purpose. + +![OneLogin Configs](https://user-images.githubusercontent.com/52545545/202557656-07b809db-51ba-4133-ae4c-c45ebf40401b.png) Once complete, save the changes and download the SAML metadata document -found unde the `More Actions` dropdown. +found unde the `More Actions` dropdown. You'll need +to copy-paste the contents of this document into the Firezone portal in the next step. ## Add SAML identity provider to Firezone In the Firezone portal, add a SAML identity provider under the Security tab by filling out the following information: -| Setting | Value | Notes | -|--- |--- |--- | -| Config ID | `onelogin` | Firezone uses this value to construct endpoints required in the SAML authentication flow (e.g., receiving assertions, login requests).| -| Label | `OneLogin` | Appears on the sign in button for authentication. | -| Metadata | see note | Upload the contents of the SAML metadata document you downloaded in the previous step from OneLogin. | +| Setting | Value | Notes | +|--- |--- |--- | +| Config ID | `onelogin` | Used to construct endpoints required in the SAML authentication flow (e.g., receiving assertions, login requests).| +| Label | `OneLogin` | Appears on the sign in button for authentication. | +| Metadata | see note | Paste the contents of the SAML metadata document you downloaded in the previous step from OneLogin. | +| Sign assertions | Checked. | | +| Sign metadata | Checked. | | +| Require signed assertions | Checked. | | +| Required signed envelopes | Checked. | | -![OneLogin SAML](https://user-images.githubusercontent.com/52545545/201445195-82d621e8-99a2-40fb-860e-9972fb86423e.png) +![OneLogin SAML](https://user-images.githubusercontent.com/52545545/202556102-5ba29d84-9610-4ffa-a516-6c89ffef4928.png) After saving the SAML config, you should see a `Sign in with OneLogin` button on your Firezone portal sign-in page.