Provider documentation

README.md

@@ -102,6 +102,8 @@ This project is licensed under the **Apache License**. This means that you can u
 
 Links to the latest stable and nightly NuGet packages for each provider, as well as a link to their integration documentation are listed in the table below.
 
+Documentation for the providers' settings can be found [here](docs/README.md "Provider documentation").
+
 If a provider you're looking for does not exist, consider making a PR to add one.
 
 | Provider | Stable | Nightly | Documentation |

docs/README.md

@@ -0,0 +1,67 @@
+# OAuth Provider Documentation
+
+This document contains some introductory information about how to integrate the
+OAuth providers in this repository into an ASP.NET Core application.
+
+It assumes a general familiarity with ASP.NET Core and authorization, and is
+intended to demonstrate how to configure it for your application, not how it
+works internally. Further integration details for a given provider can be found
+in the services' own documentation, which are linked to in the main [README](https://github.com/aspnet-contrib/AspNet.Security.OAuth.Providers#providers "Table of OAuth providers").
+
+## Generic Documentation
+
+Most of the OAuth providers in this repository can be configured by just
+specifying two settings: [`ClientId`](https://docs.microsoft.com/en-us/dotnet/api/microsoft.aspnetcore.authentication.oauth.oauthoptions.clientid "OAuthOptions.ClientId Property") and [`ClientSecret`](https://docs.microsoft.com/en-us/dotnet/api/microsoft.aspnetcore.authentication.oauth.oauthoptions.clientsecret "OAuthOptions.ClientSecret Property").
+
+Let's use the Slack provider as an example:
+
+```csharp
+services.AddAuthentication(options => /* Auth configuration */)
+        .AddSlack(options =>
+        {
+            options.ClientId = "my-client-id";
+            options.ClientSecret = "my-client-secret";
+        });
+```
+
+With just two settings, you can configure the Slack provider to authenticate users.
+
+The providers all follow a convention, so you just need to add the appropriate
+NuGet package reference and replace the word `Slack` in the method name with the
+provider name you are integrating. So for Spotify, it would be `AddSpotify()`.
+
+## Provider-Specific Documentation
+
+Any providers listed here have additional configuration that is either required
+or optional beyond the standard built-in [OAuth configuration settings](https://docs.microsoft.com/en-us/dotnet/api/microsoft.aspnetcore.authentication.oauth.oauthoptions "OAuthOptions Class").
+
+The table below lists all of the providers that provide additional configuration
+and a link to a provider-specific document for that provider. If the provider
+you are using is not listed, it does not have any specific documentation and is
+covered by the section above.
+
+| Provider | Required or Optional Settings | Documentation Link |
+|:-:|:-:|:-:|
+| Amazon | _Optional_ | [Documentation](amazon.md "Amazon provider documentation") |
+| Apple | **Required** | [Documentation](sign-in-with-apple.md "Apple provider documentation") |
+| BattleNet | **Required** | [Documentation](battlenet.md "BattleNet provider documentation") |
+| Bitbucket | _Optional_ | [Documentation](bitbucket.md "Bitbucket provider documentation") |
+| Discord | _Optional_ | [Documentation](discord.md "Discord provider documentation") |
+| EVEOnline | _Optional_ | [Documentation](eveonline.md "EVEOnline provider documentation") |
+| Foursquare | _Optional_ | [Documentation](foursquare.md "Foursquare provider documentation") |
+| GitHub | _Optional_ | [Documentation](github.md "GitHub provider documentation") |
+| Gitee | _Optional_ | [Documentation](gitee.md "Gitee provider documentation") |
+| Instagram | _Optional_ | [Documentation](instagram.md "Instagram provider documentation") |
+| LinkedIn | _Optional_ | [Documentation](linkedin.md "LinkedIn provider documentation") |
+| Odnoklassniki | _Optional_ | [Documentation](odnoklassniki.md "Odnoklassniki provider documentation") |
+| Okta | **Required** | [Documentation](okta.md "Okta provider documentation") |
+| Patreon | _Optional_ | [Documentation](patreon.md "Patreon provider documentation") |
+| QQ | _Optional_ | [Documentation](qq.md "QQ provider documentation") |
+| Reddit | _Optional_ | [Documentation](reddit.md "Reddit provider documentation") |
+| Salesforce | _Optional_ | [Documentation](salesforce.md "Salesforce provider documentation") |
+| StackExchange | _Optional_ | [Documentation](stackexchange.md "StackExchange provider documentation") |
+| SuperOffice | **Required** | [Documentation](superoffice.md "SuperOffice provider documentation") |
+| Trakt | _Optional_ | [Documentation](trakt.md "Trakt provider documentation") |
+| Twitch | _Optional_ | [Documentation](twitch.md "Twitch provider documentation") |
+| Vkontakte | _Optional_ | [Documentation](vkontakte.md "Vkontakte provider documentation") |
+| Weibo | _Optional_ | [Documentation](weibo.md "Weibo provider documentation") |

docs/amazon.md

@@ -0,0 +1,26 @@
+# Integrating the Amazon Provider
+
+## Example
+
+```csharp
+services.AddAuthentication(options => /* Auth configuration */)
+        .AddAmazon(options =>
+        {
+            options.ClientId = "my-client-id";
+            options.ClientSecret = "my-client-secret";
+
+            // Optionally request the user's postal code, if needed
+            options.Scope.Add("postal_code");
+            options.Fields.Add("postal_code");
+        });
+```
+
+## Required Additional Settings
+
+_None._
+
+## Optional Settings
+
+| Property Name | Property Type | Description | Default Value |
+|:-:|:-:|:-:|:-:|
+| `Fields` | `ISet<string>` | The fields of the user's profile to return. | `[ "email", "name", "user_id" ]` |

docs/battlenet.md

@@ -0,0 +1,23 @@
+# Integrating the BattleNet Provider
+
+## Example
+
+```csharp
+services.AddAuthentication(options => /* Auth configuration */)
+        .AddBattleNet(options =>
+        {
+            options.ClientId = "my-client-id";
+            options.ClientSecret = "my-client-secret";
+            options.Region = BattleNetAuthenticationRegion.Europe;
+        });
+```
+
+## Required Additional Settings
+
+| Property Name | Property Type | Description | Default Value |
+|:--|:--|:--|:--|
+| `Region` | [`BattleNetAuthenticationRegion`](https://github.com/aspnet-contrib/AspNet.Security.OAuth.Providers/blob/dev/src/AspNet.Security.OAuth.BattleNet/BattleNetAuthenticationRegion.cs "BattleNetAuthenticationRegion enumeration") | The region used to determine the appropriate API endpoints. | `BattleNetAuthenticationRegion.America` |
+
+## Optional Settings
+
+_None._

docs/bitbucket.md

@@ -0,0 +1,22 @@
+# Integrating the Bitbucket Provider
+
+## Example
+
+```csharp
+services.AddAuthentication(options => /* Auth configuration */)
+        .AddBitbucket(options =>
+        {
+            options.ClientId = "my-client-id";
+            options.ClientSecret = "my-client-secret";
+        });
+```
+
+## Required Additional Settings
+
+_None._
+
+## Optional Settings
+
+| Property Name | Property Type | Description | Default Value |
+|:--|:--|:--|:--|
+| `UserEmailsEndpoint` | `string` | The address of the endpoint exposing the email addresses associated with the logged in user. | `BitbucketAuthenticationDefaults.UserEmailsEndpoint` |

docs/discord.md

@@ -0,0 +1,24 @@
+# Integrating the Discord Provider
+
+## Example
+
+```csharp
+services.AddAuthentication(options => /* Auth configuration */)
+        .AddDiscord(options =>
+        {
+            options.ClientId = "my-client-id";
+            options.ClientSecret = "my-client-secret";
+        });
+```
+
+## Required Additional Settings
+
+_None._
+
+## Optional Settings
+
+| Property Name | Property Type | Description | Default Value |
+|:--|:--|:--|:--|
+| `DiscordAvatarFormat` | `string` | Gets or sets the URL format string to use for user avatar images. | `DiscordAuthenticationConstants.Urls.AvatarUrlFormat` |
+| `DiscordCdn` | `string` | The URL to use for the Discord CDN. | `DiscordAuthenticationConstants.Urls.DiscordCdn` |
+| `Prompt` | `string?` | The value to use for the `prompt` query string parameter when making HTTP requests to the authorization endpoint. | `null` |

docs/eveonline.md

@@ -0,0 +1,22 @@
+# Integrating the EVE Online Provider
+
+## Example
+
+```csharp
+services.AddAuthentication(options => /* Auth configuration */)
+        .AddEVEOnline(options =>
+        {
+            options.ClientId = "my-client-id";
+            options.ClientSecret = "my-client-secret";
+        });
+```
+
+## Required Additional Settings
+
+_None._
+
+## Optional Settings
+
+| Property Name | Property Type | Description | Default Value |
+|:--|:--|:--|:--|
+| `Server` | [`EVEOnlineAuthenticationServer`](https://github.com/aspnet-contrib/AspNet.Security.OAuth.Providers/blob/dev/src/AspNet.Security.OAuth.EVEOnline/EVEOnlineAuthenticationServer.cs "EVEOnlineAuthenticationServer enumeration") | The EVE Online server to use. | `EVEOnlineAuthenticationServer.Tranquility` |

docs/foursquare.md

@@ -0,0 +1,22 @@
+# Integrating the Foursquare Provider
+
+## Example
+
+```csharp
+services.AddAuthentication(options => /* Auth configuration */)
+        .AddFoursquare(options =>
+        {
+            options.ClientId = "my-client-id";
+            options.ClientSecret = "my-client-secret";
+        });
+```
+
+## Required Additional Settings
+
+_None._
+
+## Optional Settings
+
+| Property Name | Property Type | Description | Default Value |
+|:--|:--|:--|:--|
+| `ApiVersion` | `string` | The API version to use. | `"20150927"` |

docs/gitee.md

@@ -0,0 +1,22 @@
+# Integrating the Gitee Provider
+
+## Example
+
+```csharp
+services.AddAuthentication(options => /* Auth configuration */)
+        .AddGitee(options =>
+        {
+            options.ClientId = "my-client-id";
+            options.ClientSecret = "my-client-secret";
+        });
+```
+
+## Required Additional Settings
+
+_None._
+
+## Optional Settings
+
+| Property Name | Property Type | Description | Default Value |
+|:--|:--|:--|:--|
+| `UserEmailsEndpoint` | `string` | The address of the endpoint exposing the email addresses associated with the logged in user. | `GiteeAuthenticationDefaults.UserEmailsEndpoint` |

docs/github.md

@@ -0,0 +1,26 @@
+# Integrating the GitHub Provider
+
+## Example
+
+```csharp
+services.AddAuthentication(options => /* Auth configuration */)
+        .AddGitHub(options =>
+        {
+            options.ClientId = "my-client-id";
+            options.ClientSecret = "my-client-secret";
+
+            // Optional domain name for GitHub Enterprise on-premises deployments
+            options.EnterpriseDomain = "github.corp.local";
+        });
+```
+
+## Required Additional Settings
+
+_None._
+
+## Optional Settings
+
+| Property Name | Property Type | Description | Default Value |
+|:--|:--|:--|:--|
+| `EnterpriseDomain` | `string?` | The domain name to use for a GitHub Enterprise on-premises deployment. | `null` |
+| `UserEmailsEndpoint` | `string` | The address of the endpoint exposing the email addresses associated with the logged in user. | `GitHubAuthenticationDefaults.UserEmailsEndpoint` |

docs/instagram.md

@@ -0,0 +1,30 @@
+# Integrating the Instagram Provider
+
+⚠️ The Instagram Legacy API permission was [deprecated](https://www.instagram.com/developer/ "Instagram Developer Documentation") on the 29th of June 2020. Instagram no longer supports using their Basic Display API for authentication.
+
+From [Instagram's documentation](https://developers.facebook.com/docs/instagram-basic-display-api#authentication "Instagram Basic Display API Limitations"):
+
+> Instagram Basic Display is not an authentication solution. Data returned by the API cannot be used to authenticate your app users or log them into your app. If you need an authentication solution we recommend using Facebook Login instead.
+
+A Facebook authentication provider is [available from Microsoft](https://docs.microsoft.com/en-us/aspnet/core/security/authentication/social/facebook-logins "Facebook external login setup in ASP.NET Core").
+
+## Example
+
+```csharp
+services.AddAuthentication(options => /* Auth configuration */)
+        .AddInstagram(options =>
+        {
+            options.ClientId = "my-client-id";
+            options.ClientSecret = "my-client-secret";
+        });
+```
+
+## Required Additional Settings
+
+_None._
+
+## Optional Settings
+
+| Property Name | Property Type | Description | Default Value |
+|:--|:--|:--|:--|
+| `UseSignedRequests` | `bool` | Indicates whether requests to the Instagram API's user information endpoint should be signed. | `false` |

docs/linkedin.md

@@ -0,0 +1,24 @@
+# Integrating the LinkedIn Provider
+
+## Example
+
+```csharp
+services.AddAuthentication(options => /* Auth configuration */)
+        .AddLinkedIn(options =>
+        {
+            options.ClientId = "my-client-id";
+            options.ClientSecret = "my-client-secret";
+        });
+```
+
+## Required Additional Settings
+
+_None._
+
+## Optional Settings
+
+| Property Name | Property Type | Description | Default Value |
+|:--|:--|:--|:--|
+| `EmailAddressEndpoint` | `string` | The address of the endpoint exposing the email addresses associated with the logged in user. | `LinkedInAuthenticationDefaults.EmailAddressEndpoint` |
+| `Fields` | `ISet<string>` | The fields to retrieve from the user's profile. The possible values are documented [here](https://docs.microsoft.com/en-us/linkedin/consumer/integrations/self-serve/sign-in-with-linkedin#retrieving-member-profiles "Sign In with LinkedIn"). | `[ "id", "firstName", "lastName", "emailAddress" ]` |
+| `MultiLocaleStringResolver` | `Func<IReadOnlyDictionary<string, string>, string?, string>` | A delegate to a method that returns a localized value for a field returned for the user's profile. | A delegate to a method that returns either the `preferredLocale`, the value for [`Thread.CurrentUICulture`](https://docs.microsoft.com/en-us/dotnet/api/system.threading.thread.currentuiculture "Thread.CurrentUICulture Property") or the first value. |

docs/odnoklassniki.md

@@ -0,0 +1,23 @@
+# Integrating the Odnoklassniki Provider
+
+## Example
+
+```csharp
+services.AddAuthentication(options => /* Auth configuration */)
+        .AddOdnoklassniki(options =>
+        {
+            options.ClientId = "my-client-id";
+            options.ClientSecret = "my-client-secret";
+        });
+
+```
+
+## Required Additional Settings
+
+_None._
+
+## Optional Settings
+
+| Property Name | Property Type | Description | Default Value |
+|:--|:--|:--|:--|
+| `PublicSecret` | `string?` | The Public App Key from the application registration email. | `null` |

docs/okta.md

@@ -0,0 +1,23 @@
+# Integrating the Okta Provider
+
+## Example
+
+```csharp
+services.AddAuthentication(options => /* Auth configuration */)
+        .AddOkta(options =>
+        {
+            options.ClientId = "my-client-id";
+            options.ClientSecret = "my-client-secret";
+            options.Domain = "https://dev-000000.okta.com";
+        });
+```
+
+## Required Additional Settings
+
+| Property Name | Property Type | Description | Default Value |
+|:--|:--|:--|:--|
+| `Domain` | `string?` | The Okta domain (_Org URL_) to use for authentication. This can be found on the `/dev/console` page of the Okta admin portal for your account. | `null` |
+
+## Optional Settings
+
+_None._

docs/patreon.md

@@ -0,0 +1,23 @@
+# Integrating the Patreon Provider
+
+## Example
+
+```csharp
+services.AddAuthentication(options => /* Auth configuration */)
+        .AddPatreon(options =>
+        {
+            options.ClientId = "my-client-id";
+            options.ClientSecret = "my-client-secret";
+        });
+```
+
+## Required Additional Settings
+
+_None._
+
+## Optional Settings
+
+| Property Name | Property Type | Description | Default Value |
+|:--|:--|:--|:--|
+| `Fields` | `ISet<string>` | The list of fields to retrieve from the user information endpoint. | `[ "first_name", "full_name", "last_name", "thumb_url", "url" ]` |
+| `Includes` | `ISet<string>` | The list of related data to include from the user information endpoint. | `[]` |