Add docs for Sign in with Apple (#398)

* Add docs for Sign in with Apple

Add some documentation for the provider for Sign in with Apple.
Resolves #391.

* Fix grammar

Fix incorrect grammar.
Link code to the method declaration.

Author: martincostello

AspNet.Security.OAuth.Providers.sln

@@ -178,7 +178,12 @@ Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "AspNet.Security.OAuth.Gitee
 EndProject
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "AspNet.Security.OAuth.Deezer", "src\AspNet.Security.OAuth.Deezer\AspNet.Security.OAuth.Deezer.csproj", "{0D9EB03D-99AF-4A80-B7CE-2302A8D3747B}"
 EndProject
-Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "AspNet.Security.OAuth.NetEase", "src\AspNet.Security.OAuth.NetEase\AspNet.Security.OAuth.NetEase.csproj", "{E82424B3-0E73-4954-B6A6-BFF1029A08DE}"
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "AspNet.Security.OAuth.NetEase", "src\AspNet.Security.OAuth.NetEase\AspNet.Security.OAuth.NetEase.csproj", "{E82424B3-0E73-4954-B6A6-BFF1029A08DE}"
+EndProject
+Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "docs", "docs", "{C2CA4B38-AA21-4CA4-8799-2E8C8C06754F}"
+	ProjectSection(SolutionItems) = preProject
+		docs\sign-in-with-apple.md = docs\sign-in-with-apple.md
+	EndProjectSection
 EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
@@ -500,6 +505,7 @@ Global
 		{82AA3C52-9B98-4203-9D26-1FA6E5BAEEBD} = {C1352FD3-AE8B-43EE-B45B-F6E0B3FBAC6D}
 		{0D9EB03D-99AF-4A80-B7CE-2302A8D3747B} = {C1352FD3-AE8B-43EE-B45B-F6E0B3FBAC6D}
 		{E82424B3-0E73-4954-B6A6-BFF1029A08DE} = {C1352FD3-AE8B-43EE-B45B-F6E0B3FBAC6D}
+		{C2CA4B38-AA21-4CA4-8799-2E8C8C06754F} = {E9DAB098-A902-4EF5-9AEE-CF735DF31E35}
 	EndGlobalSection
 	GlobalSection(ExtensibilityGlobals) = postSolution
 		SolutionGuid = {C7B54DE2-6407-4802-AD9C-CE54BF414C8C}

docs/sign-in-with-apple.md

@@ -0,0 +1,73 @@
+# Sign in with Apple
+
+The [AspNet.Security.OAuth.Apple](https://www.nuget.org/packages/AspNet.Security.OAuth.Apple/ "AspNet.Security.OAuth.Apple on NuGet.org") provider for _Sign in with Apple_ requires some custom configuration compared to the other OAuth 2.0 providers in this repository.
+
+This document provides some additional information and context to help you configure the provider to successfully integrate _Sign in with Apple_ into your ASP.NET Core application.
+
+## Configuration
+
+### Client Secret
+
+Unlike other providers, the `ClientSecret` property is not used as _Sign in with Apple_ does not use a static client secret value. Instead the client secret has to be generated using a private key file provided by Apple from the Developer Portal that is used with the Key ID and Team ID to create a signed JSON Web Token (JWT).
+
+The provider comes with a built-in extension method ([`UsePrivateKey(string)`](https://github.com/aspnet-contrib/AspNet.Security.OAuth.Providers/blob/8e4c19008f518f3730bab90a980e01347ba6f3d3/src/AspNet.Security.OAuth.Apple/AppleAuthenticationOptionsExtensions.cs#L20-L33 "UsePrivateKey() extension method")) to generate they secret from a `.p8` certificate file on disk that you provide. Here's a [code example](https://github.com/martincostello/SignInWithAppleSample/blob/245bb70a164b66ec98ea3c2040a7387b0a3e8f0e/src/SignInWithApple/Startup.cs#L37-L46 "Example code to configure the Apple provider"):
+
+```csharp
+services.AddAuthentication(options => /* Auth configuration */)
+        .AddApple(options =>
+        {
+            options.ClientId = Configuration["AppleClientId"];
+            options.KeyId = Configuration["AppleKeyId"];
+            options.TeamId = Configuration["AppleTeamId"];
+
+            options.UsePrivateKey((keyId) =>
+                Environment.ContentRootFileProvider.GetFileInfo($"AuthKey_{keyId}.p8"));
+        });
+```
+
+Alternatively you can use the [`Func<string, Task<byte[]>> PrivateKeyBytes`](https://github.com/aspnet-contrib/AspNet.Security.OAuth.Providers/blob/8e4c19008f518f3730bab90a980e01347ba6f3d3/src/AspNet.Security.OAuth.Apple/AppleAuthenticationOptions.cs#L78-L85 "Definition of PrivateKeyBytes property") property of the `AppleAuthenticationOptions` class to provide a delegate to a custom method of your own that loads the private key's bytes from another location, such as Azure Key Vault, Kubernetes secrets etc.
+
+### Issues Loading Private Key
+
+If you encounter issues loading the private key of the certificate, the reasons could include one of the two scenarios:
+
+  1. Using .NET Core 2.x on Linux or macOS
+  1. Using Windows Server with IIS
+
+#### .NET Core 2.x on Linux or macOS
+
+For the first scenario, before .NET Core 3.0 non-Windows platforms did not support loading `.p8` (PKCS #8) files. If you cannot use .NET Core 3.1 or later, it is recommended that you create a `.pfx` certificate file from your `.p8` file and use that instead.
+
+Further information can be found in this GitHub issue: https://github.com/aspnet-contrib/AspNet.Security.OAuth.Providers/issues/390
+
+#### Windows Server with IIS
+
+For the second scenario, in order to load private keys Windows requires the user profile to be loaded.
+
+This can be configured manually in IIS (or via your hosting platform's admin portal), but in some web hosting scenarios such as Azure App Service's Free and Shared tiers, it is not possible to load the user profile for security reasons due to the multi-tenant architecture of such services.
+
+If you cannot load the user profile, possible solutions include:
+
+  * Upgrading to a paid tier with dedicated infrastructure, such as Azure App Service's Standard tier
+  * Loading the key from a `.pfx` file using the ephemeral key set ([`X509KeyStorageFlags.EphemeralKeySet`](https://docs.microsoft.com/en-us/dotnet/api/system.security.cryptography.x509certificates.x509keystorageflags?view=netcore-3.1 "X509KeyStorageFlags Enum on docs.microsoft.com"))
+
+Further information can be found in this GitHub issue: https://github.com/aspnet-contrib/AspNet.Security.OAuth.Providers/issues/358
+
+## Related Issues
+
+Below are links to some issues raised against this repository that were related to configuration and/or environmental issues:
+
+  * [Apple secret generation doesn't work in Azure App Service Free/Shared Tier (#358)](https://github.com/aspnet-contrib/AspNet.Security.OAuth.Providers/issues/358 "Apple secret generation doesn't work in Azure App Service Free/Shared Tier")
+  * [Allow passing in private key as string instead of p8 file (#385)](https://github.com/aspnet-contrib/AspNet.Security.OAuth.Providers/issues/385 "Allow passing in private key as string instead of p8 file")
+  * [Apple Signin redirects to a blank page 404 Error (#390)](https://github.com/aspnet-contrib/AspNet.Security.OAuth.Providers/issues/390 "Apple Signin redirects to a blank page 404 Error")
+
+## Further Reading
+
+Below are links to a number of other documentation sources, blog posts and sample code about Sign in with Apple.
+
+  * [Sign In with Apple](https://developer.apple.com/sign-in-with-apple/ "Sign In with Apple - developer.apple.com")
+  * [Sign In with Apple REST API](https://developer.apple.com/documentation/signinwithapplerestapi "Sign In with Apple REST API - developer.apple.com")
+  * [_"What the Heck is Sign In with Apple?"_](https://developer.okta.com/blog/2019/06/04/what-the-heck-is-sign-in-with-apple "What the Heck is Sign In with Apple? - developer.okta.com")
+  * [_"What is Sign In with Apple?_](https://auth0.com/blog/what-is-sign-in-with-apple-a-new-identity-provider/ "Sign In with Apple: Learn About the New Identity Provider - auth0.com")
+  * [_"Prototyping Sign In with Apple for ASP.NET Core"_](https://blog.martincostello.com/sign-in-with-apple-prototype-for-aspnet-core/ "Prototyping Sign In with Apple for ASP.NET Core")
+  * [Sign In with Apple demo app](https://signinwithapple.azurewebsites.net/ "Sign In with Apple demo app - signinwithapple.azurewebsites.net")