diff --git a/_articles/login-with-sso/saml-jumpcloud.md b/_articles/login-with-sso/saml-jumpcloud.md index 8a625f17..77eab0e1 100644 --- a/_articles/login-with-sso/saml-jumpcloud.md +++ b/_articles/login-with-sso/saml-jumpcloud.md @@ -9,18 +9,146 @@ tags: [sso, saml, jumpcloud] order: --- -This article contains sample configurations for Bitwarden **Login with SSO** (SAML 2.0) implementations with JumpCloud. +This article contains **JumpCloud-specific** help for configuring Login with SSO via SAML 2.0. For help configuring Login with SSO for another IdP, refer to [SAML 2.0 Configuration]({{site.baseurl}}/article/configure-sso-saml/). -Use this as reference material for the [Configuring Login with SSO (SAML 2.0)]({% link _articles/login-with-sso/configure-sso-saml.md%}) article. +Configuration involves working simultaneously within the Bitwarden [Business Portal]({{site.baseurl//article/about-business-portal/}}) and the JumpCloud Portal. As you proceed, we recommend having both readily available and completing steps in the order they're documented. -## JumpCloud Portal +## Open the Business Portal -The following is a sample SAML 2.0 implementation with Bitwarden in the JumpCloud Portal: +If you're coming straight from [SAML 2.0 Configuration]({{site.baseurl}}/article/sso-configure-saml/), you should already have an [Organization ID created](https://bitwarden.com/help/article/configure-sso-saml/#step-1-enabling-login-with-sso) and the SSO Configuration screen open. If you don't, open your [Business Portal]({{site.baseurl}}/article/about-business-portal/) and navigate to the SSO Configuration screen: + +{% image sso/sso-saml1.png SAML 2.0 Configuration %} + +You don't need to edit anything on this screen yet, but keep it open for easy reference. + +## Create a JumpCloud SAML App + +In the JumpCloud Portal, select **SSO** from the menu and select the {% icon fa-plus %} **Add** icon: + +{% image sso/cheatsheets/saml-jumpcloud/jc-addapp.png Add JumpCloud App %} + +Enter `Bitwarden` in the search box and select the **configure** button: + +{% image sso/cheatsheets/saml-jumpcloud/jc-bw.png Configure Bitwarden %} + +{% callout success %} +If you're more comfortable with SAML, or want more control over things like NameID Format and Signing Algorithms, create a **Custom SAML App** instead. +{% endcallout %} + +### General Info + +In the **General Info** section, configure the following information: + +|Field|Description| +|-----|-----------| +|Display Label|Give the application a Bitwarden-specific name.| + +### Single Sign-On Configuration + +In the **Single Sign-On Configuration** section, configure the following information: + +|Field|Description| +|-----|-----------| +|IdP Entity ID|Set this field to a unique, Bitwarden-specific value, e.g. `bitwardensso_yourcompany`.| +|SP Entity ID|Set this field to the pre-generated **SP Entity ID** retrieved from the Bitwarden SSO Configuration screen.

For Cloud-hosted customers, this is always `https://sso.bitwarden.com/saml2`. For self-hosted instances, this is determined by your [configured server URL]({{site.baseurl}}/article/install-on-premise/#configure-your-domain), for example `https://your.domain.com/sso/saml2`.| +|ACS URL|Set this field to the pre-generated **Assertion Consumer Service (ACS) URL** retrieved from the Bitwarden SSO Configuration screen.

For Cloud-hosted customers, this is always `https://sso.bitwarden.com/saml2/your-org-id/Acs`. For self-hosted instances, this is determined by your [configured server URL]({{site.baseurl}}/article/install-on-premise/#configure-your-domain), for example `https://your.domain.com/sso/saml2/your-org-id/Acs`.| + +#### Custom SAML App Only + +If you created a Custom SAML App, you'll also need to configure the following **Single Sign-On Configuration** fields: + +|Field|Description| +|-----|-----------| +|SAMLSubject NameID|Specify the JumpCloud attribute that will be sent in SAML responses as the NameID.| +|SAMLSubject NameID Format|Specify the format of the NameID sent in SAML responses.| +|Signature Algoritm|Select the algorithm to use to sign SAML assertions or reponses.| +|Sign Assertion|By default, JumpCloud will sign the SAML response. Check this box the sign the SAML assertion.| +|Login URL|Specify the URL from which your users will login to Bitwarden via SSO. For Cloud-hosted customers, this is always `https://vault.bitwarden.com/#/sso`. For self-hosted instances, this is determined by your [configured server URL]({{site.baseurl}}/article/install-on-premise/#configure-your-domain), for example `https://your.domain.com/#/sso`. | + +### Attributes + +In the **Single Sign-On Configuration** → **Attributes** section, construct the following SP → IdP attribute mappings. If you selected the Bitwarden App in JumpCloud, these should already be constructed: + +{% image sso/cheatsheets/saml-jumpcloud/jc-attr.png Attribute Mapping %} + +Once you're finished, select the **activate** button. + +### Download the Certificate + +Once the application is activated, use the **SSO** menu option again to open the created Bitwarden application. Select the **IDP Certificate** dropdown and **Download certificate**: + +{% image sso/cheatsheets/saml-jumpcloud/jc-cert.png Download Certificate %} + +### Bind Users Groups + +In the JumpCloud Portal, select **User Groups** from the menu: + +{% image sso/cheatsheets/saml-jumpcloud/jc-groups.png User Groups %} + +Either create a Bitwarden-specific User Group, or open the All Users default User Group. In either case, select the **Applications** tab and enable access to the created Bitwarden SSO application for that User Group: + +{% image sso/cheatsheets/saml-jumpcloud/jc-group-app.png Bind App Access %} + +{% callout success %} +Alternatively, you can bind access to User Groups directly from the **SSO** → **Bitwarden Application** screen. +{% endcallout %} + +## Back to the Business Portal + +At this point, you've configured everything you need within the context of the JumpCloud Portal. Jump back over to the Bitwarden Business Portal to complete configuration. + +The Business Portal separates configuration into two sections: + +- **SAML Service Provider Configuration** will determine the format of SAML requests. +- **SAML Identity Provider Configuration** will determine the format to expect for SAML responses. + +### Service Provider Configuration + +Configure the following fields according to the choices selected in the OneLogin Portal [during app creation](#create-a-onelogin-app): + +|Field|Description| +|-----|-----------| +|Name ID Format|If you created a Custom SAML App, set this to whatever the specified SAMLSubject NameID Format is. Otherwise, leave **Unspecified**.| +|Outbound Signing Algorithm|The algorithm Bitwarden will use to sign SAML requests.| +|Signing Behavior|Whether/when SAML requests will be signed. By default, JumpCloud will not require requests to be signed.| +|Minimum Incoming Signing Algorithm|If you created a Custom SAML App, set this to whichever Signature Algorithm you selected. Otherwise, leave as `rsa-sha256`.| +|Want Assertions Signed|If you created a Custom SAML App, check this box if you set the **Sign Assertion** option in JumpCloud. Otherwise, leave unchecked.| +|Validate Certificates|Check this box when using trusted and valid certificates from your IdP through a trusted CA. Self-signed certificates may fail unless proper trust chains are configured within the Bitwarden Login with SSO docker image.| + +When you're done with the Service Provider configuration section, **Save** your work. + +### Identity Provider Configuration + +Identity Provider Configuration will often require you to refer back to the OneLogin Portal to retrieve application values: + +|Field|Description| +|-----|-----------| +|Entity ID|Enter your JumpCloud **IdP Entity ID**, which can be retrieved from the JumpCloud [Single Sign-On Configuration screen](##single-sign-on-configuration).| +|Binding Type|Set to **Redirect**.| +|Single Sign On Service URL|Enter your JumpCloud **IdP URL**, which can be retrieved from the JumpCloud [Single Sign-On Configuration screen](##single-sign-on-configuration).| +|Single Log Out Service URL|Login with SSO currently **does not** support SLO. This option is planned for future development.| +|Artifact Resolution Service URL|For JumpCloud implementations, you can leave this field blank.| +|X509 Public Certificate|Paste the [retrieved Certificate](##download-the-certificate), removing `-----BEGIN CERTIFICATE-----` and `-----END CERTIFICATE-----`.

Extra spaces, carriage returns, and other extraneous characters **will cause certifiation validation to fail**.| +|Outbound Signing Algorithm|If you created a Custom SAML App, set this to whichever Signature Algorithm you selected. Otherwise, leave as `rsa-sha256`.| +|Allow Unsolicited Authentication Response|Login with SSO currently **does not** support unsolicited (IdP-Initiated) SAML assertions. This option is planned for future development.| +|Disable Outbound Logout Requests|Login with SSO currently **does not** support SLO. This option is planned for future development.| +|Want Authentication Requests Signed|Whether JumpCloud expects SAML requests to be signed.| + +## Test the Configuration + +Once your configuration is complete, test it by navigating to [https://vault.bitwarden.com](https://vault.bitwarden.com){:target="\_blank"} and selecting the **Enterprise Single Sign-On** button: + +{% image /sso/sso-button-lg.png Enterprise Single Sign-On button %} + +Enter the [configured Organization Identifier](#) and select **Log In**. If your implementation is successfully configured, you'll be redirected to the JumpCloud login screen: + +{% image sso/cheatsheets/saml-jumpcloud/jc-login.png JumpCloud Login %} + +After you authenticate with your JumpCloud credentials, enter your Bitwarden Master Password to decrypt your Vault! + +{% comment %} {% image sso/cheatsheets/saml-jumpcloud/saml-jumpcloud.png %} -## Bitwarden Business Portal - -The following is a sample SAML 2.0 implementation with JumpCloud in the Bitwarden Business Portal: - {% image sso/cheatsheets/saml-jumpcloud/saml-jumpcloud-bitwarden.png %} +{% endcomment %} diff --git a/images/sso/cheatsheets/saml-jumpcloud/jc-addapp.png b/images/sso/cheatsheets/saml-jumpcloud/jc-addapp.png new file mode 100644 index 00000000..ece9e1ce Binary files /dev/null and b/images/sso/cheatsheets/saml-jumpcloud/jc-addapp.png differ diff --git a/images/sso/cheatsheets/saml-jumpcloud/jc-attr.png b/images/sso/cheatsheets/saml-jumpcloud/jc-attr.png new file mode 100644 index 00000000..6530f029 Binary files /dev/null and b/images/sso/cheatsheets/saml-jumpcloud/jc-attr.png differ diff --git a/images/sso/cheatsheets/saml-jumpcloud/jc-bw.png b/images/sso/cheatsheets/saml-jumpcloud/jc-bw.png new file mode 100644 index 00000000..b1c70341 Binary files /dev/null and b/images/sso/cheatsheets/saml-jumpcloud/jc-bw.png differ diff --git a/images/sso/cheatsheets/saml-jumpcloud/jc-cert.png b/images/sso/cheatsheets/saml-jumpcloud/jc-cert.png new file mode 100644 index 00000000..0ad2c33f Binary files /dev/null and b/images/sso/cheatsheets/saml-jumpcloud/jc-cert.png differ diff --git a/images/sso/cheatsheets/saml-jumpcloud/jc-group-app.png b/images/sso/cheatsheets/saml-jumpcloud/jc-group-app.png new file mode 100644 index 00000000..d2d192b4 Binary files /dev/null and b/images/sso/cheatsheets/saml-jumpcloud/jc-group-app.png differ diff --git a/images/sso/cheatsheets/saml-jumpcloud/jc-groups.png b/images/sso/cheatsheets/saml-jumpcloud/jc-groups.png new file mode 100644 index 00000000..3c3aff53 Binary files /dev/null and b/images/sso/cheatsheets/saml-jumpcloud/jc-groups.png differ diff --git a/images/sso/cheatsheets/saml-jumpcloud/jc-login.png b/images/sso/cheatsheets/saml-jumpcloud/jc-login.png new file mode 100644 index 00000000..5256b854 Binary files /dev/null and b/images/sso/cheatsheets/saml-jumpcloud/jc-login.png differ