diff --git a/custom-words.txt b/custom-words.txt index aaf6cc11e..41956a306 100644 --- a/custom-words.txt +++ b/custom-words.txt @@ -45,7 +45,6 @@ minio MVVM NGRX OIDCS -oktapreview Omnisharp onboarded opid diff --git a/docs/getting-started/server/sso/config.png b/docs/getting-started/server/sso/config.png deleted file mode 100644 index 587221314..000000000 Binary files a/docs/getting-started/server/sso/config.png and /dev/null differ diff --git a/docs/getting-started/server/sso/index.md b/docs/getting-started/server/sso/index.md index 272514396..735feeb53 100644 --- a/docs/getting-started/server/sso/index.md +++ b/docs/getting-started/server/sso/index.md @@ -7,18 +7,144 @@ sidebar_custom_props: ## Setup and configuration -You can set up SSO for development using: +For local development, we use +[Docker Test SAML 2.0 Identity Provider](https://github.com/kenchan0130/docker-simplesamlphp), which +we have pre-configured in an `idp` Docker container for easy setup. -- [a local IdP](./local.md) (recommended) -- [Okta](./okta.mdx) +### Prerequisites -## Desktop client +1. Bitwarden server set up and configured with the following server projects running: + - Identity + - API + - SSO (located at `server/bitwarden_license/src/Sso`) +2. Local web client running. +3. An enterprise account created with the testing credit card located here: + [Advanced Server Setup](../advanced-setup.md). -:::note +### Configure the IdP -This workaround may not be required - SSO may just work, even on a development build. Try it first! +1. Open your local web client and navigate to your organization → Settings → Single Sign-On. +2. Tick the "Allow SSO authentication" box. +3. Come up with and enter an SSO Identifier. +4. Select "SAML 2.0" as the SSO type. Don't save or exit this page yet, you'll need to come back to + it later. +5. Open a new terminal and navigate to the `dev` folder in your server repository, e.g. + ```bash + cd ~/Projects/server/dev + ``` +6. Open your `.env` file and set the following environment variables using the "SP Entity ID" and + "Assertion Consumer Service (ACS) URL" values from the SSO configuration page opened in step #4 + above: -::: + ```bash + IDP_SP_ENTITY_ID={SP Entity ID} + IDP_SP_ACS_URL={ACS URL} + ``` + + :::note + + You should have created this `.env` file during your initial server setup. You can refer back to + the `.env.example` file if required. + + ::: + +7. (Optional) You may generate a certificate to sign SSO requests. You can do this with a script + made for your OS of choice. + + ```bash + # Mac + ./create_certificates_mac.sh + + # Windows + .\create_certificates_windows.ps1 + + # Linux + ./create_certificates_linux.sh + ``` + + Paste the thumbprint, for example `0BE8A0072214AB37C6928968752F698EEC3A68B5`, into your + `secrets.json` file under `globalSettings` > `identityServer` > `certificateThumbprint`. Update + your secrets as [shown here](../guide.md#configure-user-secrets). + +8. Make a copy of the provided `authsources.php.example` file, which contains the configuration for + your IdP users. + + ```bash + cp authsources.php.example authsources.php + ``` + + By default, this file has two users configured: `user1` and `user2`, and both have the password + `password`. You can add or modify users by following this format, or just use the defaults. See + [here](https://github.com/kenchan0130/docker-simplesamlphp#advanced-usage) for more information + about customizing this file. + +9. Start the docker container: + + ```bash + docker compose --profile idp up -d + ``` + +10. You can test your user configuration by navigating to + [http://localhost:8090/simplesaml](http://localhost:8090/simplesaml) and clicking Authentication + → Test Configured Authentication Sources → `example-userpass`. You should be able to log in with + the users you’ve configured. + +### Configure Bitwarden + +1. Go back to your window with the SSO configuration page open. +2. Complete the following values in the SAML Identity Provider Configuration section: + - Entity ID: + ``` + http://localhost:8090/simplesaml/saml2/idp/metadata.php + ``` + - Single Sign On Service URL: + ``` + http://localhost:8090/simplesaml/saml2/idp/SSOService.php + ``` + - X509 Public Certificate + - Get this by opening a new tab and navigating to the Entity ID URL above. It will open (or + download) an XML file. Copy and paste the value _between_ the `` tags + (it should look like a base64-encoded string). +3. Save your SSO configuration. + +Your SSO is now ready to go! + +## Updating the IdP configuration + +### Users + +To add or change users, just edit `authsources.php`. Your changes will take effect immediately, +however any currently authenticated users will have to log out for changes to their account to take +effect. + +To log out as a user, navigate to +[http://localhost:8090/simplesaml/module.php/core/authenticate.php?as=example-userpass](http://localhost:8090/simplesaml/module.php/core/authenticate.php?as=example-userpass) +and click Logout. Alternatively, you can use a private browsing session. + +### SAML configuration + +To change the Entity ID or ACS URL, edit the `.env` file and then restart the Docker container: + +```bash +docker compose --profile idp up -d +``` + +## Troubleshooting + +### Bitwarden server throws “unknown userId” error + +You’re missing the `uid` claim for the user in `authsources.php`. + +### IdP displays a "Metadata not found" error + +Your Entity ID and/or ACS URL in `.env` are incorrect. Make sure they match the values shown in the +SSO configuration page of the Admin Console. If you change the values in `.env`, run the +`docker compose` command above to restart the container with the updated variables. + +Note that the URL shown on the error page is not sourced from your `.env` file, so do not be +confused if the URL on the error page is correct. + +### Desktop client does not open correctly after SSO The desktop client opens a browser to complete the SSO authentication flow. After you have authenticated with the IdP, your browser will redirect to a `bitwarden://` URI. This URI would @@ -39,7 +165,7 @@ You can work around this as follows: ![](./devtools.png) -1. Go back to your desktop client and open the developer tools. -2. Paste the following command into the console and press enter: +6. Go back to your desktop client and open the developer tools. +7. Paste the following command into the console and press enter: `window.location.href = ''` -3. Your desktop client should now complete the SSO login +8. Your desktop client should now complete the SSO login diff --git a/docs/getting-started/server/sso/local.md b/docs/getting-started/server/sso/local.md deleted file mode 100644 index ea513eefa..000000000 --- a/docs/getting-started/server/sso/local.md +++ /dev/null @@ -1,147 +0,0 @@ -# Local IdP - -This article will show you how to set up a local SSO Identity Provider (IdP) for testing purposes. - -This uses -[Docker Test SAML 2.0 Identity Provider](https://github.com/kenchan0130/docker-simplesamlphp). - -## Prerequisites - -1. Bitwarden server set up and configured with the following server projects running: - - Identity - - API - - SSO (located at `server/bitwarden_license/src/Sso`) - -2. Local web client running. - -3. An enterprise account created with the testing credit card located here: - [Advanced Server Setup](../advanced-setup.md). - -## Configure the IdP - -1. Open your local web client and navigate to your organization → Settings → Single Sign-On. - -2. Tick the "Allow SSO authentication" box. - -3. Come up with and enter an SSO Identifier. - -4. Select "SAML 2.0" as the SSO type. Don't save or exit this page yet, you'll need to come back to - it later. - -5. Open a new terminal and navigate to the `dev` folder in your server repository, e.g. - - ```bash - cd ~/Projects/server/dev - ``` - -6. Open your `.env` file and set the following environment variables using the "SP Entity ID" and - "Assertion Consumer Service (ACS) URL" values from the SSO configuration page opened in step #4 - above: - - ```bash - IDP_SP_ENTITY_ID={SP Entity ID} - IDP_SP_ACS_URL={ACS URL} - ``` - - :::note - - You should have created this `.env` file during your initial server setup. You can refer back to - the `.env.example` file if required. - - ::: - -7. (Optional) You may generate a certificate to sign SSO requests. You can do this with a script - made for your OS of choice. - - ```bash - # Mac - ./create_certificates_mac.sh - - # Windows - .\create_certificates_windows.ps1 - - # Linux - ./create_certificates_linux.sh - ``` - - Paste the thumbprint, for example `0BE8A0072214AB37C6928968752F698EEC3A68B5`, into your - `secrets.json` file under `globalSettings` > `identityServer` > `certificateThumbprint`. Update - your secrets as [shown here](../guide.md#configure-user-secrets). - -8. Make a copy of the provided `authsources.php.example` file, which contains the configuration for - your IdP users. - - ```bash - cp authsources.php.example authsources.php - ``` - - By default, this file has two users configured: `user1` and `user2`, and both have the password - `password`. You can add or modify users by following this format, or just use the defaults. See - [here](https://github.com/kenchan0130/docker-simplesamlphp#advanced-usage) for more information - about customizing this file. - -9. Start the docker container: - - ```bash - docker compose --profile idp up -d - ``` - -10. You can test your user configuration by navigating to - [http://localhost:8090/simplesaml](http://localhost:8090/simplesaml), then Authentication → test - configured authentication sources → `example-userpass`. You should be able to log in with the - users you’ve configured. - -## Configure Bitwarden - -1. Go back to your window with the SSO configuration page open. -2. Complete the following values in the SAML Identity Provider Configuration section: - 1. Entity ID: - ``` - http://localhost:8090/simplesaml/saml2/idp/metadata.php - ``` - 2. Single Sign On Service URL: - ``` - http://localhost:8090/simplesaml/saml2/idp/SSOService.php - ``` - 3. X509 Public Certificate: get this by opening a new tab and navigating to the Entity ID URL - above. It will open (or download) an XML file. Copy and paste the value _between_ the - `` tags (it should look like a B64 encoded string). - -3. Save your SSO configuration - -Your SSO is now ready to go! - -## Updating the IdP configuration - -### Users - -To add or change users, just edit `authsources.php`. Your changes will take effect immediately, -however any currently authenticated users will have to log out for changes to their account to take -effect. - -To log out as a user, navigate to -[http://localhost:8090/simplesaml/module.php/core/authenticate.php?as=example-userpass](http://localhost:8090/simplesaml/module.php/core/authenticate.php?as=example-userpass) -and click Logout. Alternatively, you can use a private browsing session. - -### SAML configuration - -To change the Entity ID or ACS URL, edit the `.env` file and then restart the Docker container: - -```bash -docker compose --profile idp up -d -``` - -## Troubleshooting - -### Bitwarden server throws “unknown userId” error - -You’re missing the `uid` claim for the user in `authsources.php`. - -### IdP displays a "Metadata not found" error - -Your Entity ID and/or ACS URL in `.env` are incorrect. Make sure they match the values shown in the -SSO configuration page of the Admin Console. If you change the values in `.env`, run the -`docker compose` command above to restart the container with the updated variables. - -Note that the URL shown on the error page is not sourced from your `.env` file, so do not be -confused if the URL on the error page is correct. diff --git a/docs/getting-started/server/sso/okta.mdx b/docs/getting-started/server/sso/okta.mdx deleted file mode 100644 index 987f96d00..000000000 --- a/docs/getting-started/server/sso/okta.mdx +++ /dev/null @@ -1,64 +0,0 @@ -import configImage from "./config.png"; - -# Okta - -This guide will set up basic SSO auth using Okta. This is for testing ONLY and should not be linked -to any production environment. - -## Prerequisites - -1. Bitwarden server set up and configured with the following server projects running: - - Identity - - API - - SSO (located at `server/bitwarden_license/src/Sso`) - -2. Access to Development collection in your Bitwarden Vault - -3. An enterprise account created with the testing credit card located here: - [Advanced Server Setup](../advanced-setup.md). - -## Steps - -In your browser do the following steps to access Okta. - -1. Launch the "[oktapreview.com](http://oktapreview.com)" login item in the Development collection -2. Log in using those credentials -3. Expand the "Directory" section on the left menu panel -4. Click "People" -5. Click "Add Person" and create a profile for yourself - - Use the same email as your local Bitwarden user - - For the Password field, choose "Set by admin" and set a secure password - - Uncheck "User must change password on first login" -6. Click "Applications" in the top menu bar -7. You should now see a list of our test apps. For the purpose of local testing, click the - "Bitwarden Test 2" application. The Client Credentials and other information for this - application will be listed, which you can use in the subsequent steps. - -Open a separate browser tab to configure SSO in your local Bitwarden web vault. - -1. Log into your web vault and navigate to the organization you want to enable SSO for -2. Click `Settings` for the organization and enter an Identifier. This should be unique - it can - just be the organization name. Click Save. -3. Go to `Manage > Single Sign-On` and input the following information: - -| Type | OpenId Connect | -| ---------------------------------- | ---------------------------------- | -| Authority | https://dev-836655.oktapreview.com | -| Client ID | Copy from Okta | -| Client Secret | Copy from Okta | -| OIDCS Redirect Behavior | Redirect GET | -| Get Claims From User Info Endpoint | :white_check_mark: | - -You can now log in using SSO. - -:::note - -You must have your vault URL set in your client endpoints - -::: - -## Example configuration - -Any fields not shown should be blank. - -