diff --git a/_articles/login-with-sso/configure-sso-oidc.md b/_articles/login-with-sso/configure-sso-oidc.md index fec57008..c24605c2 100644 --- a/_articles/login-with-sso/configure-sso-oidc.md +++ b/_articles/login-with-sso/configure-sso-oidc.md @@ -1,6 +1,6 @@ --- layout: article -title: Configure Login with SSO (OIDC) +title: OIDC Configuration categories: [login-with-sso] featured: false popular: false @@ -8,90 +8,71 @@ tags: [sso, oidc, openid, idp, identity] order: 04 --- -This article will guide you through the steps required to configure Login with SSO for OpenID Connect (OIDC) authentication. +## Step 1: Set an Organization Identifier -{% callout info %} -**Configuration will vary provider-to-provider.** Refer to the following Provider Samples as you configure Login with SSO: +Users who [authenticate their identity using SSO]({{site.baseurl}}/article/sso-access-your-vault) will be required to enter an **Organization Identifier** that indicates the Organization (and therefore, the SSO integration) to authenticate against. To set a unique Organization Identifier: -- [Okta Sample]({% link _articles/login-with-sso/oidc-okta.md %}) - -{% endcallout %} - -## Step 1: Enabling Login with SSO - -Complete the following steps to enable Login with SSO for OIDC authentication: - -1. In the Web Vault, navigate to your Organization and open the **Settings** tab. -2. In the **Identifier** field, enter a unique identifier for your Organization: +1. Log in to your [Web Vault](https://vault.bitwarden.com){:target="\_blank"} and open your Organization. +2. Open the **Settings** tab and enter a unique **Identifier** for your Organization. {% image /sso/org-id.png Enter an Identifier %} +3. **Save** your changes before exiting this page. - Don't forget to **Save** your identifier. Users will be required to enter this **Identifier** upon login. +{% callout success %} +You'll need to share this value with users once the configuration is ready to be used. +{% endcallout %} -3. Navigate to the **Business Portal**. +## Step 2: Enable Login with SSO - {% image /organizations/business-portal-button-overlay.png Business Portal button %} +Once you have your Organization Identifier, you can proceed to enabling and configuring your integration. To enable Login with SSO: -4. Select the **Single Sign-On** button. -5. Check the **Enabled** checkbox. -6. From the **Type** dropdown menu, select the **OpenID Connect** option. +1. From your Organization Vault, navigate to the **Business Portal**: -After selecting **OpenID Connect**, this page will display a list of configuration fields you will need to configure. + {% image /organizations/business-portal-button-overlay.png Business Portal %} -Keep this page on-hand, as you will need the values of **Callback Path** and **Signed Out Callback Path** to complete [Step 2](#step-2-configure-your-idp). +2. From the Business Portal menu bar, check that the correct Organization is listed and select the **Single Sign-On** button: -## Step 2: Configure Your IdP +{% image sso/sso-bp-1.png Business Portal Menu%} +3. Check the **Enabled** checkbox. +4. From the **Type** dropdown menu, select the **OpenID Connect** option. If you intend to use SAML instead, switch over the the [SAML Configuration Guide]({{site.baseurl}}/article/configure-sso-saml/). -Before you can complete your configuration settings, you must configure your IdP to receive requests from and send responses to Bitwarden. +## Step 3: Configuration -{% comment %} -PLACEHOLDER TO ADD PROVIDER SCREENSHOTS Configuration can vary provider-to-provider. Refer to the following samples for assistance: +From this point on, **implementation will vary provider-to-provider**. Jump to one of our specific **Implementation Guides** for help completing the Configuration process: -- [{% icon fa-download %} Okta OIDC Sample]({{site.baseurl}}/files/bitwarden_export.csv) -{% endcomment %} +|Provider|Guide| +|--------|-----| +|Azure|[Azure Implementation Guide]({{site.baseurl}}/article/oidc-azure/)| +|Okta|[Okta Implementation Guide]({{site.baseurl}}/article/oidc-okta/)| -When you've successfully set your IdP, return to the Bitwarden Business Portal to complete your OIDC configuration. +### Configuration Reference Materials -## Step 3: OpenID Connect Configuration +The following sections will define fields configured in the [Bitwarden Business Portal]({{site.baseurl}}/article/about-business-portal), agnostic of which IdP you're integrating with. Fields that must be configured will be marked (**Required**). -Fields in this section should come from the configured values in [Step 2: Configure your IdP](#step-2-configure-your-idp). +{% callout success %} +**Unless you're comfortable with OpenID Connect**, we recommend using one of the [above Implementation Guides](#step-3-configuration) instead of the following generic material. +{% endcallout %} -Required fields will be marked. Failing to provide a value for a required field will cause your configuration to be rejected. +|Field|Description| +|-----|-----------| +|Callback Path|(**Automatically generated**) The URL for authentication automatic redirect. For Cloud-hosted customers, this is always `https://sso.bitwarden.com/oidc-signin`. 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/oidc-signin`.| +|Signed Out Callback Path|(**Automatically generated**) The URL for sign-out automatic redirect. For Cloud-hosted customers, this is always `https://sso.bitwarden.com/oidc-signedout`. 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/oidc-signedout`.| +|Authority|(**Required**) The URL of your Authorization Server ("Authority"), which Bitwarden will perform authentication against. For example, `https://your.domain.okta.com/oauth2/default` or `https://login.microsoft.com//v2.0`.| +|Client ID|(**Required**) An identifier for the OIDC Client. This value is typically specific to a constructed IdP App Integration, for example an [Azure App Registration]({{site.baseurl}}/article/oidc-azure/) or [Okta Web App]({{site.baseurl}}/article/oidc-okta/).| +|Client Secret|(**Required**) The client secret used in conjunction with the Client ID to exchange for an access token. This value is typically specific to a constructed IdP App Integration, for example an [Azure App Registration]({{site.baseurl}}/article/oidc-azure/) or [Okta Web App]({{site.baseurl}}/article/oidc-okta/).| +|Metadata Address|(**Required if Authority is not valid**) A Metadata URL where Bitwarden can access Authorization Server metadata as a JSON object. For example, `https://your.domain.okta.com/oauth2/default/.well-known/oauth-authorization-server`.| +|OIDC Redirect Behavior|(**Required**) Method used by the IdP to response to authentication requests from Bitwarden. Options include **Form POST** and **Redirect GET**.| +|Get Claims From User Info Endpoint|Enable this option if you receive URL too long errors (HTTP 414), truncated URLS, and/or failures during SSO.| +|Additional/Custom Scopes|Define custom scopes to be added to the request (comma-delimited). | +|Additional/Custom User ID Claim Types|Define custom claim type keys for user identification (comma-delimited). When defined, custom claim types are searched for before falling back on standard types.| +|Additional/Custom Email Claim Types|Define custom claim type keys for users' email addresses (comma-delimited). When defined, custom claim types are searched for before falling back on standard types.| +|Additional/Custom Name Claim Types|Define custom claim type keys for users' full names or display names (comma-delimited). When defined, custom claim types are searched for before falling back on standard types.| +|Requested Authentication Context Class Reference values|Define Authentication Context Class Reference identifiers (`acr_values`) (space-delimited). List `acr_values` in preference-order.| +|Expected "acr" Claim Value in Response|Define the `acr` Claim Value for Bitwarden to expect and validate in the response.| -{% image /sso/sso-oidc.png OpenID Connect Configuration screen %} +### OIDC Attributes & Claims -#### Callback Path -The URL for Bitwarden authentication automatic redirect. This value will be automatically generated. For all Cloud-hosted instances, `https://sso.bitwarden.com/oidc-signin`. For self-hosted instances, domain is based on your configured Server URL. - -#### Signed Out Callback Path -The URL for Bitwarden sign-out automatic redirect. This value will be automatically generated. For all Cloud-hosted instances, `https://sso.bitwarden.com/oidc-signedout`. For self-hosted instances, domain is based on your configured Server URL. - -#### Authority (*Required*) -Your Identity Provider URL or the Authority that Bitwarden will perform authentication against. - -#### Client ID (*Required*) -The Client identifier used for Bitwarden, as configured in your Identity Provider. - -#### Client Secret (*Required*) -*May be required depending on your IdP's configuration, needs, or requirements* - -A secret used in conjunction with **Client ID** to exchange for an authentication token. - -#### Metadata Address (*Required if Authority is not a valid URL*) - -Identity Provider information which Bitwarden will perform authentication against (*e.g.* Okta Metadata URI). - -#### OIDC Redirect Behavior -Method used by the IdP to respond to Bitwarden authentication requests. Options include: -- Form POST -- Redirect GET - -#### Get Claims From User Info Endpoint -Check this checkbox if you receive `URI Too Long (HTTP 414)` errors, truncated URLs, or failures during SSO. - -## OIDC Attributes & Claims - -An **email address is required for account provisioning**, which can be passed as any of the attributes or claims in the below table. +An **email address is required for account provisioning**, which can be passed as any of the attributes or claims in the below table. A unique user identifier is also highly recommended. If absent, Email will be used in its place to link the user. diff --git a/_articles/login-with-sso/oidc-azure.md b/_articles/login-with-sso/oidc-azure.md new file mode 100644 index 00000000..183aac1b --- /dev/null +++ b/_articles/login-with-sso/oidc-azure.md @@ -0,0 +1,87 @@ +--- +layout: article +title: Azure OIDC Implementation +categories: [login-with-sso] +featured: false +popular: false +hidden: true +tags: [sso, oidc, azure] +order: +--- + +This article contains **Azure-specific** help for configuring Login with SSO via OpenID Connect (OIDC). For help configuring Login with SSO for another OIDC IdP, or for configuring Azure via SAML 2.0, see [OIDC Configuration]({{site.baseurl}}/article/configure-sso-oidc/) or [Azure SAML Implementation]({{site.baseurl}}/article/saml-azure/). + +Configuration involves working simultaneously within the Bitwarden [Bitwarden Business Portal]({{site.baseurl}}/article/about-business-portal/) and the Azure Portal. As you proceed, we recommend having both readily available and completing steps in the order they're documented. + +## Open the Business Portal + +If you're coming straight from [OIDC Configuration]({{site.baseurl}}/article/configure-sso-oidc/), you should already have an **Organization ID** created and SSO **Enabled**. If you don't, follow [steps 1 and 2 of that document]({{site.baseurl}}/article/configure-sso-oidc/) and return to this guide. + +Open your [Business Portal]({{site.baseurl}}/article/about-business-portal/) and navigate to the SSO Configuration screen: + +{% image sso/sso-oidc1.png OIDC Configuration %} + +You don't need to edit anything on this screen yet, but keep it open for easy reference. + +## Create an App Registration + +In the Azure Portal, navigate to **App registrations** and select the **New registration** button: + +{% image sso/cheatsheets/oidc-azure/azure-newapp.png Create App Registration %} + +On the **Register an application** screen, give your app a Bitwarden-specific name and specify which accounts should be able to use the application. This selection will determine which users can use Bitwarden Login with SSO. + +### Register a Redirect URI + +Select **Authentication** from the navigation and select the **Add a platform** button: + +{% image sso/cheatsheets/oidc-azure/azure-redirecturis.png Register a Redirect URI %} + +Select the **Web** option on the Configure platforms screen and enter your **Callback Path** in the Redirect URIs input. + +{% callout info %} +Callback Path can be retrieved from the Bitwarden SSO Configuration screen. For Cloud-hosted customers, this is always `https://sso.bitwarden.com/oidc-signin`. 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/oidc-signin`. +{% endcallout %} + +### Create a Client Secret + +Select **Certificates & secrets** from the navigation, and select the **New client secret** button: + +{% image sso/cheatsheets/oidc-azure/azure-newcert.png Create Client Secret %} + +Give the certificate a Bitwarden-specific name, and choose an expiration timeframe. + + + +## Bitwarden Business Portal Configuration + +At this point, you've configured everything you need within the context of the Azure Portal. Jump back over to the Bitwarden Business Portal to configure the following fields: + +|Field|Description| +|-----|-----------| +|Authority|Enter `https://login.microsoft.com//v2.0`, where `TENANT_ID` is the **Directory (tenant) ID** value retrieved from the App registration's Overview screen.| +|Client ID|Enter the App registration's **Application (client) ID**, which can be retrieved from the Overview screen.| +|Client Secret|Enter the **Secret ID** of the [created Client Secret](#create-a-client-secret).| +|Metadata Address|For Azure implementations as documented, you can leave this field blank.| +|OIDC Redirect Behavior|Select either **Form POST** or **Redirect GET**.| +|Get Claims From User Info Endpoint|Enable this option if you receive URL too long errors (HTTP 414), truncated URLS, and/or failures during SSO.| +|Additional/Custom Scopes|Define custom scopes to be added to the request (comma-delimited). | +|Additional/Custom User ID Claim Types|Define custom claim type keys for user identification (comma-delimited). When defined, custom claim types are searched for before falling back on standard types.| +|Additional/Custom Email Claim Types|Define custom claim type keys for users' email addresses (comma-delimited). When defined, custom claim types are searched for before falling back on standard types.| +|Additional/Custom Name Claim Types|Define custom claim type keys for users' full names or display names (comma-delimited). When defined, custom claim types are searched for before falling back on standard types.| +|Requested Authentication Context Class Reference values|Define Authentication Context Class Reference identifiers (`acr_values`) (space-delimited). List `acr_values` in preference-order.| +|Expected "acr" Claim Value in Response|Define the `acr` Claim Value for Bitwarden to expect and validate in the response.| + +When you're done configuring these fields, **Save** your work. + +## 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]({{site.baseurl}}/article/configure-sso-saml/#step-1-enabling-login-with-sso) and select **Log In**. If your implementation is successfully configured, you'll be redirected to the Microsoft login screen: + +{% image sso/cheatsheets/saml-azure/az-login.png Azure login screen %} + +After you authenticate with your Azure credentials, enter your Bitwarden Master Password to decrypt your Vault! diff --git a/_articles/login-with-sso/oidc-okta.md b/_articles/login-with-sso/oidc-okta.md index 6ed50f93..79a93b0a 100644 --- a/_articles/login-with-sso/oidc-okta.md +++ b/_articles/login-with-sso/oidc-okta.md @@ -1,29 +1,102 @@ --- layout: article title: Okta OIDC Implementation -categories: [] +categories: [login-with-sso] featured: false popular: false hidden: true tags: [sso, oidc, okta] order: --- -This article contains sample configurations for Bitwarden **Login with SSO** (OIDC) implementations with Okta. +This article contains **Okta-specific** help for configuring Login with SSO via OpenID Connect (OIDC). For help configuring Login with SSO for another OIDC IdP, or for configuring Okta via SAML 2.0, see [OIDC Configuration]({{site.baseurl}}/article/configure-sso-oidc/) or [Okta SAML Implementation]({{site.baseurl}}/article/saml-okta/). -Use this as reference material for the [Configure Login with SSO (OIDC)]({% link _articles/login-with-sso/configure-sso-oidc.md%}) article. +Configuration involves working simultaneously within the Bitwarden [Business Portal]({{site.baseurl}}/article/about-business-portal/) and the Okta Admin Portal. As you proceed, we recommend having both readily available and completing steps in the order they're documentated. -## Okta Portal +## Open the Business Portal -The following is a sample OIDC implementation with Bitwarden in the Okta Portal: +If you're coming straight from [OIDC Configuration]({{site.baseurl}}/article/configure-sso-oidc/), you should already have an **Organization ID** created and SSO **Enabled**. If you don't, follow [steps 1 and 2 of that document]({{site.baseurl}}/article/configure-sso-oidc/) and return to this document. + +Open your [Business Portal]({{site.baseurl}}/article/about-business-portal/) and navigate to the SSO Configuration screen: + +{% image sso/sso-oidc1.png OIDC Configuration %} + +You don't need to edit anything on this screen yet, but keep it open for easy reference. + +## Create an Okta App + +In the Okta Admin Portal, select **Applications** → **Applications** from the navigation. On the Applications screen, select the **Create App Integration** button. For Sign-on method, select **OIDC - OpenID Connect**. For Application type, select **Web Application**: + +{% image sso/cheatsheets/oidc-okta/okta-createapp.png %} + +On the **New Web App Integration** screen, configure the following fields: + +|Field|Description| +|-----|-----------| +|App integration name|Give the app a Bitwarden-specific name.| +|Grant type|Enable the following [grant types](https://developer.okta.com/docs/concepts/oauth-openid/#choosing-an-oauth-2-0-flow){:target="\_blank"}:

- Client acting on behalf of itself → **Client Credentials**
- Client acting on behalf of a user → **Authorization Code**| +|Sign-in redirect URIs|Set this field to your **Callback Path**, which can be retrieved from the Bitwarden SSO Configuration screen.

For Cloud-hosted customers, this is always `https://sso.bitwarden.com/oidc-signin`. 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/oidc-signin`.| +|Sign-out redirect URIs|Set this field to your **Signed Out Callback Path**, which can be retrieved from the Bitwarden SSO Configuration screen.| +|Assignments|Use this field to designate whether all or only select groups will be able to use Bitwarden Login with SSO.| + +Once configured, select the **Next** button. + +### Get Client Credentials + +On the Application screen, copy the **Client ID** and **Client secret** for the newly created Okta app: + +{% image sso/cheatsheets/oidc-okta/okta-clientcredentials.png App Client Credentials %} + +You'll need to use both values [during a later step](#bitwarden-business-portal-configuration). + +### Get Authorization Server Information + +Select **Security** → **API** from the navigation. From the **Authorization Servers** list, select the server you'd like to use for this implementation. On the **Settings** tab for the server, copy the **Issuer** and **Metadata URI** values: + +{% image sso/cheatsheets/oidc-okta/okta-authserver.png Okta Authorization Server Settings %} + +You'll need to use both values [during the next step](#bitwarden-business-portal-configuration). + +## Bitwarden Business Portal Configuration + +At this point, you've configured everything you need within the context of the Okta Admin Portal. Jump back over to the Bitwarden Business Portal to configure the following fields: + +|Field|Description| +|-----|-----------| +|Authority|Enter the [retrieved Issuer URI](#get-authorization-server-information) for your Authorization Server.| +|Client ID|Enter the [retrieved Client ID](#get-client-credentials) for your Okta app.| +|Client Secret|Enter the [retrieved Client secret](#get-client-credentials) for your Okta app.| +|Metadata Address|Enter the [retrieved Metadata URI](#get-client-authorization-server-information) for your Authorization Server.| +|OIDC Redirect Behavior|Select **Redirect GET**. Okta currently does not support Form POST.| +|Get Claims From User Info Endpoint|Enable this option if you receive URL too long errors (HTTP 414), truncated URLS, and/or failures during SSO.| +|Additional/Custom Scopes|Define custom scopes to be added to the request (comma-delimited). | +|Additional/Custom User ID Claim Types|Define custom claim type keys for user identification (comma-delimited). When defined, custom claim types are searched for before falling back on standard types.| +|Additional/Custom Email Claim Types|Define custom claim type keys for users' email addresses (comma-delimited). When defined, custom claim types are searched for before falling back on standard types.| +|Additional/Custom Name Claim Types|Define custom claim type keys for users' full names or display names (comma-delimited). When defined, custom claim types are searched for before falling back on standard types.| +|Requested Authentication Context Class Reference values|Define Authentication Context Class Reference identifiers (`acr_values`) (space-delimited). List `acr_values` in preference-order.| +|Expected "acr" Claim Value in Response|Define the `acr` Claim Value for Bitwarden to expect and validate in the response.| + +When you're done configuring these fields, **Save** your work. + +## 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 Okta login screen: + +{% image sso/cheatsheets/saml-okta/okta-login.png Log in with Okta %} + +After you authenticate with your Okta credentials, enter your Bitwarden Master Password to decrypt your Vault! + +{% comment %} {% image sso/cheatsheets/oidc-okta/oidc-okta1.png %} {% image sso/cheatsheets/oidc-okta/oidc-okta2.png %} -## Bitwarden Business Portal - -The following is a sample OIDC implementation with Okta in the Bitwarden Business Portal: - {% image sso/cheatsheets/oidc-okta/oidc-okta4.png %} {% image sso/cheatsheets/oidc-okta/oidc-okta3.png %} + +{% endcomment %} diff --git a/images/sso/cheatsheets/oidc-azure/azure-newapp.png b/images/sso/cheatsheets/oidc-azure/azure-newapp.png new file mode 100644 index 00000000..22709910 Binary files /dev/null and b/images/sso/cheatsheets/oidc-azure/azure-newapp.png differ diff --git a/images/sso/cheatsheets/oidc-azure/azure-newcert.png b/images/sso/cheatsheets/oidc-azure/azure-newcert.png new file mode 100644 index 00000000..6113f472 Binary files /dev/null and b/images/sso/cheatsheets/oidc-azure/azure-newcert.png differ diff --git a/images/sso/cheatsheets/oidc-azure/azure-redirecturis.png b/images/sso/cheatsheets/oidc-azure/azure-redirecturis.png new file mode 100644 index 00000000..b913ab91 Binary files /dev/null and b/images/sso/cheatsheets/oidc-azure/azure-redirecturis.png differ diff --git a/images/sso/cheatsheets/oidc-okta/okta-authserver.png b/images/sso/cheatsheets/oidc-okta/okta-authserver.png new file mode 100644 index 00000000..40a20a44 Binary files /dev/null and b/images/sso/cheatsheets/oidc-okta/okta-authserver.png differ diff --git a/images/sso/cheatsheets/oidc-okta/okta-clientcredentials.png b/images/sso/cheatsheets/oidc-okta/okta-clientcredentials.png new file mode 100644 index 00000000..eccb4b5a Binary files /dev/null and b/images/sso/cheatsheets/oidc-okta/okta-clientcredentials.png differ diff --git a/images/sso/cheatsheets/oidc-okta/okta-createapp.png b/images/sso/cheatsheets/oidc-okta/okta-createapp.png new file mode 100644 index 00000000..78a799b5 Binary files /dev/null and b/images/sso/cheatsheets/oidc-okta/okta-createapp.png differ diff --git a/images/sso/sso-bp-1.png b/images/sso/sso-bp-1.png new file mode 100644 index 00000000..9aa96a02 Binary files /dev/null and b/images/sso/sso-bp-1.png differ diff --git a/images/sso/sso-oidc1.png b/images/sso/sso-oidc1.png new file mode 100644 index 00000000..ea207d84 Binary files /dev/null and b/images/sso/sso-oidc1.png differ