OIDC Docs (#661)

* initial drafts of oidc docs

* updates for custom claim + acr fields

* fix header tag

_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/<TENANT_ID>/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.
 

_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/<TENANT_ID>/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!

_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"}:<br><br>- Client acting on behalf of itself &rarr; **Client Credentials**<br>- Client acting on behalf of a user &rarr; **Authorization Code**|
+|Sign-in redirect URIs|Set this field to your **Callback Path**, which can be retrieved from the Bitwarden SSO Configuration screen.<br><br>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** &rarr; **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 %}