Add security best practices (#4853)

1 files changed, 33 insertions, 16 deletions

diff --git a/Documentation/microsoft-team.md b/Documentation/microsoft-team.md
index 2c958047..e347cee3 100644
--- a/Documentation/microsoft-team.md
+++ b/Documentation/microsoft-team.md
@@ -1,6 +1,6 @@
 # Microsoft Team Onboarding
 
-If you are new to Microsoft or working with the .NET Team, you will need to onboard into various GitHub projects in order to get your work done.
+If you work on or with the .NET Team, you will need to onboard into various GitHub projects in order to get your work done.
 
 ## Join .NET teams in dotnet and Microsoft orgs
 
@@ -47,30 +47,47 @@ The browser extension is recommended. The VS code extension is optional.
 
 Join teams to gain write access to repos:
  * Request team membership via https://repos.opensource.microsoft.com/teams
- * Find the right teams - e.g. `dotnet-coreclr`, `dotnet-corefx`, etc.
- * Ask someone if you don't know which team to join.
+ * Ask someone if you don't know which team(s) to join.
  * Select `Request to join this team` on the right side - it will send email request to maintainers of the team
 
-## Service Accounts
+## Security best practices
 
-Service accounts should also be linked. For more details, see [Service accounts for GitHub](https://docs.opensource.microsoft.com/github/service-accounts.html).
+Enabling 2FA doesn't necessarily mean your account is secure. SMS (phone texts) is [not secure](https://en.wikipedia.org/wiki/SIM_swap_scam) as a 2FA method and should be avoided if possible. You can see [failed login attempts](https://github.com/settings/security-log?q=action%3Auser.failed_login) on your account to get some sense of the risk you have.
 
+The following best practices are required for org owners, and recommended for repo admins. 
 
-## Guidelines
+* Do register a [security key(s)](https://www.yubico.com/works-with-yubikey/catalog/github/) as a two factor method.
+* Do register an authenticator app -- registering a one-time-password with an app like 1Password is recommended (not tied to your phone).
+* Do store recorvery codes in a safe place, like [OneDrive Vault](https://www.microsoft.com/en-us/microsoft-365/onedrive/personal-vault), 2FA-protected OneNote or in a password vault like 1Password.
+* Do register your GitHub account with your 2FA-protected Facebook account for GitHub account recovery. This is the absolute last recovery option and is considered secure (even if your Facebook account is breached).
+* Do not use SMS for 2FA or as a recovery fallback.
 
-* [Contributing to .NET Core](https://github.com/dotnet/coreclr/blob/master/Documentation/project-docs/contributing.md)
-* [What you can expect from Maintainers](https://github.com/dotnet/core/blob/master/Documentation/contributing/maintainers.md)
+Note: If you completely lose access to login to your account, GitHub support will not be able to recover your account. That's why all of these options are covered.
+
+A few more notes on hardware keys:
+
+* You should have at least one hardware key that does not travel with you, but is stored in a secure location (like at home) as a last resort in case you lose access to other factors.
+* If you have a FIDO2 key, it can be used with [mysignins](https://mysignins.microsoft.com/).
+* If you have USB-C and USB-A only devices, and want to use hardware keys for them, then you need [separate keys](https://www.yubico.com/works-with-yubikey/catalog/github/). This explains why the example below has three keys registered (one securely stored at home, and two keys for daily use for USB-C and USB-A only devices).
+* You can use Windows Hello to signin as a hardware key. This is fine to use, but doesn't replace the need for hardware key that you store in a secure location.Your Windows Hello key is not tied to you, but the machine. It won't survive hardware failures or re-installing Windows.
+
+A correctly configured account should look similar to the following:
 
+![image](https://user-images.githubusercontent.com/2608468/83581219-1421f780-a4f3-11ea-8f01-3a27afe4ddac.png)
 
-## Tools
+Please test your security key to ensure it works. You need to see a dialog similar to the following (that says "security key"):
 
-* [Corporate GitHub Chrome Extension](https://repos.opensource.microsoft.com/settings/security/tokens/extension)
-* [CodeFlow Chrome Extension](https://chrome.google.com/webstore/detail/codeflow/aphnoipocoffpdafmiidfmaiadhilelm)
+![image](https://user-images.githubusercontent.com/2608468/83581665-56980400-a4f4-11ea-8096-ddd553d28e18.png)
 
+Facebook-based account recovery registration will look similar to the following:
 
-## Resources
+![image](https://user-images.githubusercontent.com/2608468/83581770-965eeb80-a4f4-11ea-993d-ad39bae391c2.png)
 
-* [.NET Core "Home Repo"](https://github.com/dotnet/core) (links to install daily builds)
-* [Introduction to the Common Language Runtime (CLR)](https://github.com/dotnet/coreclr/blob/master/Documentation/botr/intro-to-clr.md)
-* [The Book of the Runtime](https://github.com/dotnet/coreclr/blob/master/Documentation/botr/README.md)
-* [CoreCLR Docs](https://github.com/dotnet/coreclr/tree/master/Documentation)
+## Service Accounts
+
+Service accounts should also be linked. For more details, see [Service accounts for GitHub](https://docs.opensource.microsoft.com/github/service-accounts.html).
+
+## Guidelines
+
+* [Contributing to .NET Core](https://github.com/dotnet/runtime/blob/master/CONTRIBUTING.md)
+* [What you can expect from Maintainers](https://github.com/dotnet/core/blob/master/Documentation/contributing/maintainers.md)