diff --git a/_articles/login-with-sso/saml-onelogin.md b/_articles/login-with-sso/saml-onelogin.md index 22b6d36c..2fc33e90 100644 --- a/_articles/login-with-sso/saml-onelogin.md +++ b/_articles/login-with-sso/saml-onelogin.md @@ -1,32 +1,148 @@ --- layout: article -title: OneLogin SAML Implementation -categories: [] +title: OneLogin SAML Configuration +categories: [login-with-sso] featured: false popular: false hidden: true tags: [sso, saml, onelogin] order: --- +This article contains **OneLogin-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/). -This article contains sample configurations for Bitwarden **Login with SSO** (SAML 2.0) implementations with OneLogin. +Configuration involves working simultaneously within the Bitwarden [Business Portal]({{site.baseurl}}/article/about-business-portal/) and the OneLogin Portal. As you proceed, we recommend having both readily available and completing steps in the order they're documented. -Use this as reference material for the [Configuring Login with SSO (SAML 2.0)]({% link _articles/login-with-sso/configure-sso-saml.md%}) article. +## Open the Business Portal -## OneLogin 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: -The following is a sample SAML 2.0 implementation with Bitwarden in the OneLogin Portal: +{% image sso/sso-saml1.png SAML 2.0 Configuration %} -{% image sso/cheatsheets/saml-onelogin/saml-onelogin1.png %} +You don't need to edit anything on this screen yet, but keep it open for easy reference. -{% image sso/cheatsheets/saml-onelogin/saml-onelogin2.png %} +## Create a OneLogin App + +In the OneLogin Portal, navigate to the the **Applications** screen and select the **Add App** button: + +{% image sso/cheatsheets/saml-onelogin/ol-addapp.png Add an Application %} + +In the search bar, type `saml test connector` and select the **SAML Test Connector (Advanced)** app: + +{% image sso/cheatsheets/saml-onelogin/ol-addapp2.png SAML Test Connector App %} + +Give your application a Bitwarden-specific **Display Name** and select the **Save** button. + +### Configuration + +Select **Configuration** from the left-hand navigation and configure the following information, some of which you'll need to retreive from the Bitwarden Business Portal: + +{% image sso/cheatsheets/saml-onelogin/ol-appconfig.png %} + +|Application Setting|Description| +|----------------|-----------| +|Audience (EntityID)|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`.| +|Recipient|Set this field to the same pre-generated **SP Entity ID** used for the **Audience (Entity ID)** setting.| +|ACS (Consumer) URL Validator|Despite being marked **Required** by OneLogin, you don't actually need to enter information into this field to integrate with Bitwarden. Skip to the next field, **ACS (Consumer) URL**.| +|ACS (Consumer) 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`.| +|SAML initiator|Select **Service Provider**. Login with SSO does not currently support IdP-initiated SAML assertions.| +|SAML nameID Format|Set this field to the [SAML NameID Format](https://docs.oracle.com/cd/E19316-01/820-3886/ggwbz/index.html){:target="\_blank"} you want to use for SAML assertions.| +|SAML signature element|By default, OneLogin will sign the SAML Response. You can set this to **Assertion** or **Both**, and | + +Select the **Save** button to finish your Configuration settings. + +### Parameters + +Select **Parameters** from the left-hand navigation and use the {% icon fa-plus %} **Add** icon to create the following custom parameters: + +|Field Name|Value| +|----------|-----| +|email|Email| +|firstname|First Name| +|lastname|Last Name| + +Select the **Save** button to finish your custom parameters. + +### SSO + +Select **SSO** from the left-hand navigation and complete the following: + +1. Select the **View Details** link under your X.509 Certificate: + + {% image sso/cheatsheets/saml-onelogin/ol-viewcert.png View your Cert %} + + On the Certificate screen, download or copy your X.509 PEM Certificate, as you'll need to [use it later](#identity-provider-configuration). Once copied, return to the main SSO screen. +2. Set your **SAML Signature Algorithm**. +3. Take note of your **Issuer URL** and **SAML 2.0 Endpoint (HTTP)**. You'll need to [use these values shortly](#identity-provider-configuration). + +### Access + +Select **Access** from the left-hand navigation. In the **Roles** section, assign application access to all the roles you'd like to be able to use Bitwarden. Most implementations create a Bitwarden-specific role and instead opt to assign based on a catch-all (for example, **Default**) or based on pre-existing roles. + +{% image sso/cheatsheets/saml-onelogin/ol-roles.png Role Assignment %} + +## Back to the Business Portal + +At this point, you've configured everything you need within the context of the OneLogin 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|Set this field to whatever you selected for the OneLogin **SAML nameID Format** field [during App Configuration](#configuration).| +|Outbound Signing Algorithm|Algorithm used to sign SAML requests, by default `sha-256`.| +|Signing Behavior|Whether/when SAML requests will be signed. By default, OneLogin will not require requests to be signed.| +|Minimum Incoming Signing Algorithm|Set this field to whatever you selected for the **SAML Signature Algorithm** [during App Configuration](#configuration)| +|Want Assertions Signed|Check this box if you set the **SAML signature element** in OneLogin to **Assertion** or **Both** [during App Configuration](#configuration).| +|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 OneLogin **Issuer URL**, which can be retrieved from the [OneLogin app SSO screen](#sso).| +|Binding Type|Set to **HTTP Post** (as indicated in the SAML 2.0 Endpoint (HTTP)).| +|Single Sign On Service URL|Enter your OneLogin **SAML 2.0 Endpoint (HTTP)**, which can be retrieved from the [OneLogin app SSO screen](#sso).| +|Single Log Out Service URL|Login with SSO currently **does not** support SLO. This option is planned for future development, however you may pre-configure it if you wish.| +|Artifact Resolution Service URL|For OneLogin implementations, you can leave this field blank.| +|X509 Public Certificate|Paste the [retrieved X.509 Certificate](#sso), removing `-----BEGIN CERTIFICATE-----` and `-----END CERTIFICATE-----`.

Extra spaces, carriage returns, and other extraneous characters **will cause certifiation validation to fail**.| +|Outbound Signing Algorithm|Select the SAML Signature Algorithm selected in the [OneLogin SSO](#sso) configuration section.| +|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 OneLogin 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 OneLogin login screen: + +{% image sso/cheatsheets/saml-onelogin/ol-login.png OneLogin Login %} + +After you authenticate with your OneLogin credentials, enter your Bitwarden Master Password to decrypt your Vault! + + +{% comment %} {% image sso/cheatsheets/saml-onelogin/saml-onelogin3.png %} {% image sso/cheatsheets/saml-onelogin/saml-onelogin4.png %} -## Bitwarden Business Portal +{% image sso/cheatsheets/saml-onelogin/saml-onelogin5.png %} -The following is a sample SAML 2.0 implementation with OneLogin in the Bitwarden Business Portal: +{% image sso/cheatsheets/saml-onelogin/saml-onelogin1.png %} -{% image sso/cheatsheets/saml-onelogin/saml-onelogin5.png %} +{% image sso/cheatsheets/saml-onelogin/saml-onelogin2.png %} +{% endcomment %} diff --git a/images/sso/cheatsheets/saml-onelogin/ol-addapp.png b/images/sso/cheatsheets/saml-onelogin/ol-addapp.png new file mode 100644 index 00000000..eff3726a Binary files /dev/null and b/images/sso/cheatsheets/saml-onelogin/ol-addapp.png differ diff --git a/images/sso/cheatsheets/saml-onelogin/ol-addapp2.png b/images/sso/cheatsheets/saml-onelogin/ol-addapp2.png new file mode 100644 index 00000000..499638e3 Binary files /dev/null and b/images/sso/cheatsheets/saml-onelogin/ol-addapp2.png differ diff --git a/images/sso/cheatsheets/saml-onelogin/ol-appconfig.png b/images/sso/cheatsheets/saml-onelogin/ol-appconfig.png new file mode 100644 index 00000000..06a6bffb Binary files /dev/null and b/images/sso/cheatsheets/saml-onelogin/ol-appconfig.png differ diff --git a/images/sso/cheatsheets/saml-onelogin/ol-login.png b/images/sso/cheatsheets/saml-onelogin/ol-login.png new file mode 100644 index 00000000..bd12c3ff Binary files /dev/null and b/images/sso/cheatsheets/saml-onelogin/ol-login.png differ diff --git a/images/sso/cheatsheets/saml-onelogin/ol-roles.png b/images/sso/cheatsheets/saml-onelogin/ol-roles.png new file mode 100644 index 00000000..7bb27b10 Binary files /dev/null and b/images/sso/cheatsheets/saml-onelogin/ol-roles.png differ diff --git a/images/sso/cheatsheets/saml-onelogin/ol-viewcert.png b/images/sso/cheatsheets/saml-onelogin/ol-viewcert.png new file mode 100644 index 00000000..14ac2b8b Binary files /dev/null and b/images/sso/cheatsheets/saml-onelogin/ol-viewcert.png differ