From 8f7389f15397b8519f103c97492e7c551f7fe4a6 Mon Sep 17 00:00:00 2001 From: Chad Scharf <3904944+cscharf@users.noreply.github.com> Date: Mon, 28 Sep 2020 09:48:05 -0400 Subject: [PATCH] Added contributing.md file and link in readme (#950) --- CONTRIBUTING.md | 84 +++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 2 +- 2 files changed, 85 insertions(+), 1 deletion(-) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000..3e59cae58 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,84 @@ +# Contributing: Local Dev Environment Setup +For local development and running the Server (Api, Identity, etc.) you'll need to setup a few things in order to make that work, connect to your own local SQL instance (docker image), as well as have appropriate certificates available for performing encryption, signing, data protection, etc. + +## User Secrets +You will need to manage user secrets for each site project in the Server solution. This includes predominately the Api and Identity projects, although there are other, lessor used ones that may also need it depending on what you're doing, but these 2 set the foundation. + +### Self Hosted vs. Not +It is highly recommended that you use the `selfHosted: true` setting when running locally so the system will not attempt to use cloud services without a valid connection string. Otherwise there are emulators that allow you to run local dev instances of various Azure and/or AWS services such as local-stack, etc. or you can use your own Azure accounts for provisioning the necessary services and set the connection strings accordingly. + +### Visual Studio on Windows +You can simply right-click on the Project and "View User Secrets" (or something like that), easy peasy. + +### Visual Studio on macOS +You must open a terminal and go to each project directory. Once there you initiate and create the blank user secrets file by running, + +```bash +dotnet user-secrets init +``` + +You can then view/list any secrets you have set by running, `dotnet user-secrets list`. For more info see: [Safe storage of app secrets in development in ASP.NET Core](https://docs.microsoft.com/en-us/aspnet/core/security/app-secrets?view=aspnetcore-3.1&tabs=linux) + +### Rider +* Navigate to **Preferences -> Plugins** and Install .NET Core User Secrets +* You can now right click on the a project (ex: Api), go to 'tools' and 'Open project user secrets' + +## User Secrets - Certificates +Once you have your user secrets files setup, you'll need to generate 3 of your own certificates for use in local development. + +### Generate Certificates +1. Within a terminal, navigate to ~/Desktop +2. Run the following command to create an Identity Server (Dev) certificate + key (separate) +```bash +openssl req -x509 -newkey rsa:4096 -sha256 -nodes -keyout identity_server_dev.key -out identity_server_dev.crt -subj "/CN=Bitwarden Identity Server Dev" -days 3650 +``` +3. Run the following command to create an Identity Server (Dev) certificate + key pfx file based on the previously created certificate + key +4. You will be prompted to enter a password - remember this because you’ll need it for your keychain +```bash +openssl pkcs12 -export -out identity_server_dev.pfx -inkey identity_server_dev.key -in identity_server_dev.crt -certfile identity_server_dev.crt +``` +5. Run the following command to create a Data Protection (Dev) certificate + key (separate) +```bash +openssl req -x509 -newkey rsa:4096 -sha256 -nodes -keyout data_protection_dev.key -out data_protection_dev.crt -subj "/CN=Bitwarden Data Protection Dev" -days 3650 +``` +6. Once created, do the same process for a Data Protection (Dev) certificate + key pfx file +7. Again, create a password so you can save the files in your keychain +```bash +openssl pkcs12 -export -out data_protection_dev.pfx -inkey data_protection_dev.key -in data_protection_dev.crt -certfile data_protection_dev.crt +``` +8. Add all of the generated pfx files to your login keychain by double-clicking on the files + 1. You’ll need to enter the respective generated password for each +9. Update the Trust options for each certificate to `always trust` - don’t worry, this is secure…. :) +10. Get the SHA 1 thumbprint for the Identity and Data Protection certificates and them to your Api User Secrets file +11. Copy + Paste the entire file into the Identity secrets + 1. Access the Identity user secrets the same way Api user + +## Running and Debugging +Launching the entire bitwarden/server solution for use with the bitwarden/web and other client projects. + +### Prerequisites +* Docker MSSQL instance running (and accessible localhost) +* An ADS connection to the `vault_dev` database is running +* [Node.js](https://nodejs.org/en/) is installed with updated PATH variables for launch +* User secrets are configured, password updated to MSSQL database + +### Visual Studio for macOS +You can right click on each project, **Identity** and then **Api**, in order, and click _Start Debugging Project_. + +You can also, alternatively if you only need them running locally w/o debugging, open a terminal and navigate to each respective .csproj location and type, + +```bash +dotnet run +``` + +NOTE: when doing this the port number on the URL may be different and you'll need to update any client configuration(s) and/or user secrets accordingly (typically the Api user secrets for the Identity URL). + +### Rider +* From within Rider, launch both the Api project and the Identity project + * This is done by hitting the play button for each project separately + +### Notes +* Don’t be alarmed when the default localhost:port for both projects opens and it shows a 404 error + * Test the Api deployment: http://localhost:5000/alive + * Test the Identity deployment: http://localhost:33657/.well-known/openid-configuration + * You should not see any errors but rather responses on the webpage(s) diff --git a/README.md b/README.md index 07980613f..c59b48b59 100644 --- a/README.md +++ b/README.md @@ -97,6 +97,6 @@ Invoke-RestMethod -OutFile bitwarden.ps1 ` ## Contribute -Code contributions are welcome! Visual Studio or VS Code is highly recommended if you are working on this project. Please commit any pull requests against the `master` branch. +Code contributions are welcome! Visual Studio or VS Code is highly recommended if you are working on this project. Please commit any pull requests against the `master` branch. Please see [`CONTRIBUTING.md`](CONTRIBUTING.md) for more info (and feel free to contribute to that guide as well). Security audits and feedback are welcome. Please open an issue or email us privately if the report is sensitive in nature. You can read our security policy in the [`SECURITY.md`](SECURITY.md) file. We also run a program on [HackerOne](https://hackerone.com/bitwarden).