Skip to content

Commit 7d84184

Browse files
martincostellomartincostello
authored
Provider documentation (#460)
* Add provider documentation index Add an initial documentation index for the providers for #459. * Link to ClientId and ClientSecret Link to the Microsoft documentation for ClientId and ClientSecret. Add missing github.md file. * Link to docs from README Link to the new docs from the README. * Add Amazon docs Add the Amazon provider documentation. * Add provider-specific documentation Add some provider-specific documentation for BattleNet through GitHub. * Add Instagram provider documentation Relates to #441. * Tidy up XML documentation Tidy up some of the XML documentation for the Discord and Instagram options. * More provider documentation Add docs for LinkedIn through to QQ. * Add remaining provider documentation Add documentation for the Reddit through Weibo providers. * Tidy up XML documentation Update some property documentation for consistency and clarity. * Simplify constant usage Add a static for SuperOfficeAuthenticationConstants to make the code lines shorter. * Document Apple provider properties Add documentation for the Apple provider's configuration options. * Link to enumerations Add links to the definition of the different enumerations. * Fix class name Fix incorrect class name being used. * Update index Add the required/optional values for all providers. * Minor docs tidy-up Format string constants as strings. Add link to enum. * Fix typo Use the right kind of apostrophe. * Link to OAuthOptions Add a link to the OAuthOptions class.
1 parent 2637825 commit 7d84184

32 files changed

+650
-40
lines changed

‎README.md

+2
Original file line numberDiff line numberDiff line change
@@ -102,6 +102,8 @@ This project is licensed under the **Apache License**. This means that you can u
102102

103103
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.
104104

105+
Documentation for the providers' settings can be found [here](docs/README.md "Provider documentation").
106+
105107
If a provider you're looking for does not exist, consider making a PR to add one.
106108

107109
| Provider | Stable | Nightly | Documentation |

‎docs/README.md

+67
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
# OAuth Provider Documentation
2+
3+
This document contains some introductory information about how to integrate the
4+
OAuth providers in this repository into an ASP.NET Core application.
5+
6+
It assumes a general familiarity with ASP.NET Core and authorization, and is
7+
intended to demonstrate how to configure it for your application, not how it
8+
works internally. Further integration details for a given provider can be found
9+
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").
10+
11+
## Generic Documentation
12+
13+
Most of the OAuth providers in this repository can be configured by just
14+
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").
15+
16+
Let's use the Slack provider as an example:
17+
18+
```csharp
19+
services.AddAuthentication(options => /* Auth configuration */)
20+
.AddSlack(options =>
21+
{
22+
options.ClientId = "my-client-id";
23+
options.ClientSecret = "my-client-secret";
24+
});
25+
```
26+
27+
With just two settings, you can configure the Slack provider to authenticate users.
28+
29+
The providers all follow a convention, so you just need to add the appropriate
30+
NuGet package reference and replace the word `Slack` in the method name with the
31+
provider name you are integrating. So for Spotify, it would be `AddSpotify()`.
32+
33+
## Provider-Specific Documentation
34+
35+
Any providers listed here have additional configuration that is either required
36+
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").
37+
38+
The table below lists all of the providers that provide additional configuration
39+
and a link to a provider-specific document for that provider. If the provider
40+
you are using is not listed, it does not have any specific documentation and is
41+
covered by the section above.
42+
43+
| Provider | Required or Optional Settings | Documentation Link |
44+
|:-:|:-:|:-:|
45+
| Amazon | _Optional_ | [Documentation](amazon.md "Amazon provider documentation") |
46+
| Apple | **Required** | [Documentation](sign-in-with-apple.md "Apple provider documentation") |
47+
| BattleNet | **Required** | [Documentation](battlenet.md "BattleNet provider documentation") |
48+
| Bitbucket | _Optional_ | [Documentation](bitbucket.md "Bitbucket provider documentation") |
49+
| Discord | _Optional_ | [Documentation](discord.md "Discord provider documentation") |
50+
| EVEOnline | _Optional_ | [Documentation](eveonline.md "EVEOnline provider documentation") |
51+
| Foursquare | _Optional_ | [Documentation](foursquare.md "Foursquare provider documentation") |
52+
| GitHub | _Optional_ | [Documentation](github.md "GitHub provider documentation") |
53+
| Gitee | _Optional_ | [Documentation](gitee.md "Gitee provider documentation") |
54+
| Instagram | _Optional_ | [Documentation](instagram.md "Instagram provider documentation") |
55+
| LinkedIn | _Optional_ | [Documentation](linkedin.md "LinkedIn provider documentation") |
56+
| Odnoklassniki | _Optional_ | [Documentation](odnoklassniki.md "Odnoklassniki provider documentation") |
57+
| Okta | **Required** | [Documentation](okta.md "Okta provider documentation") |
58+
| Patreon | _Optional_ | [Documentation](patreon.md "Patreon provider documentation") |
59+
| QQ | _Optional_ | [Documentation](qq.md "QQ provider documentation") |
60+
| Reddit | _Optional_ | [Documentation](reddit.md "Reddit provider documentation") |
61+
| Salesforce | _Optional_ | [Documentation](salesforce.md "Salesforce provider documentation") |
62+
| StackExchange | _Optional_ | [Documentation](stackexchange.md "StackExchange provider documentation") |
63+
| SuperOffice | **Required** | [Documentation](superoffice.md "SuperOffice provider documentation") |
64+
| Trakt | _Optional_ | [Documentation](trakt.md "Trakt provider documentation") |
65+
| Twitch | _Optional_ | [Documentation](twitch.md "Twitch provider documentation") |
66+
| Vkontakte | _Optional_ | [Documentation](vkontakte.md "Vkontakte provider documentation") |
67+
| Weibo | _Optional_ | [Documentation](weibo.md "Weibo provider documentation") |

‎docs/amazon.md

+26
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
# Integrating the Amazon Provider
2+
3+
## Example
4+
5+
```csharp
6+
services.AddAuthentication(options => /* Auth configuration */)
7+
.AddAmazon(options =>
8+
{
9+
options.ClientId = "my-client-id";
10+
options.ClientSecret = "my-client-secret";
11+
12+
// Optionally request the user's postal code, if needed
13+
options.Scope.Add("postal_code");
14+
options.Fields.Add("postal_code");
15+
});
16+
```
17+
18+
## Required Additional Settings
19+
20+
_None._
21+
22+
## Optional Settings
23+
24+
| Property Name | Property Type | Description | Default Value |
25+
|:-:|:-:|:-:|:-:|
26+
| `Fields` | `ISet<string>` | The fields of the user's profile to return. | `[ "email", "name", "user_id" ]` |

‎docs/battlenet.md

+23
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# Integrating the BattleNet Provider
2+
3+
## Example
4+
5+
```csharp
6+
services.AddAuthentication(options => /* Auth configuration */)
7+
.AddBattleNet(options =>
8+
{
9+
options.ClientId = "my-client-id";
10+
options.ClientSecret = "my-client-secret";
11+
options.Region = BattleNetAuthenticationRegion.Europe;
12+
});
13+
```
14+
15+
## Required Additional Settings
16+
17+
| Property Name | Property Type | Description | Default Value |
18+
|:--|:--|:--|:--|
19+
| `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` |
20+
21+
## Optional Settings
22+
23+
_None._

‎docs/bitbucket.md

+22
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
# Integrating the Bitbucket Provider
2+
3+
## Example
4+
5+
```csharp
6+
services.AddAuthentication(options => /* Auth configuration */)
7+
.AddBitbucket(options =>
8+
{
9+
options.ClientId = "my-client-id";
10+
options.ClientSecret = "my-client-secret";
11+
});
12+
```
13+
14+
## Required Additional Settings
15+
16+
_None._
17+
18+
## Optional Settings
19+
20+
| Property Name | Property Type | Description | Default Value |
21+
|:--|:--|:--|:--|
22+
| `UserEmailsEndpoint` | `string` | The address of the endpoint exposing the email addresses associated with the logged in user. | `BitbucketAuthenticationDefaults.UserEmailsEndpoint` |

‎docs/discord.md

+24
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
# Integrating the Discord Provider
2+
3+
## Example
4+
5+
```csharp
6+
services.AddAuthentication(options => /* Auth configuration */)
7+
.AddDiscord(options =>
8+
{
9+
options.ClientId = "my-client-id";
10+
options.ClientSecret = "my-client-secret";
11+
});
12+
```
13+
14+
## Required Additional Settings
15+
16+
_None._
17+
18+
## Optional Settings
19+
20+
| Property Name | Property Type | Description | Default Value |
21+
|:--|:--|:--|:--|
22+
| `DiscordAvatarFormat` | `string` | Gets or sets the URL format string to use for user avatar images. | `DiscordAuthenticationConstants.Urls.AvatarUrlFormat` |
23+
| `DiscordCdn` | `string` | The URL to use for the Discord CDN. | `DiscordAuthenticationConstants.Urls.DiscordCdn` |
24+
| `Prompt` | `string?` | The value to use for the `prompt` query string parameter when making HTTP requests to the authorization endpoint. | `null` |

‎docs/eveonline.md

+22
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
# Integrating the EVE Online Provider
2+
3+
## Example
4+
5+
```csharp
6+
services.AddAuthentication(options => /* Auth configuration */)
7+
.AddEVEOnline(options =>
8+
{
9+
options.ClientId = "my-client-id";
10+
options.ClientSecret = "my-client-secret";
11+
});
12+
```
13+
14+
## Required Additional Settings
15+
16+
_None._
17+
18+
## Optional Settings
19+
20+
| Property Name | Property Type | Description | Default Value |
21+
|:--|:--|:--|:--|
22+
| `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

+22
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
# Integrating the Foursquare Provider
2+
3+
## Example
4+
5+
```csharp
6+
services.AddAuthentication(options => /* Auth configuration */)
7+
.AddFoursquare(options =>
8+
{
9+
options.ClientId = "my-client-id";
10+
options.ClientSecret = "my-client-secret";
11+
});
12+
```
13+
14+
## Required Additional Settings
15+
16+
_None._
17+
18+
## Optional Settings
19+
20+
| Property Name | Property Type | Description | Default Value |
21+
|:--|:--|:--|:--|
22+
| `ApiVersion` | `string` | The API version to use. | `"20150927"` |

‎docs/gitee.md

+22
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
# Integrating the Gitee Provider
2+
3+
## Example
4+
5+
```csharp
6+
services.AddAuthentication(options => /* Auth configuration */)
7+
.AddGitee(options =>
8+
{
9+
options.ClientId = "my-client-id";
10+
options.ClientSecret = "my-client-secret";
11+
});
12+
```
13+
14+
## Required Additional Settings
15+
16+
_None._
17+
18+
## Optional Settings
19+
20+
| Property Name | Property Type | Description | Default Value |
21+
|:--|:--|:--|:--|
22+
| `UserEmailsEndpoint` | `string` | The address of the endpoint exposing the email addresses associated with the logged in user. | `GiteeAuthenticationDefaults.UserEmailsEndpoint` |

‎docs/github.md

+26
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
# Integrating the GitHub Provider
2+
3+
## Example
4+
5+
```csharp
6+
services.AddAuthentication(options => /* Auth configuration */)
7+
.AddGitHub(options =>
8+
{
9+
options.ClientId = "my-client-id";
10+
options.ClientSecret = "my-client-secret";
11+
12+
// Optional domain name for GitHub Enterprise on-premises deployments
13+
options.EnterpriseDomain = "github.corp.local";
14+
});
15+
```
16+
17+
## Required Additional Settings
18+
19+
_None._
20+
21+
## Optional Settings
22+
23+
| Property Name | Property Type | Description | Default Value |
24+
|:--|:--|:--|:--|
25+
| `EnterpriseDomain` | `string?` | The domain name to use for a GitHub Enterprise on-premises deployment. | `null` |
26+
| `UserEmailsEndpoint` | `string` | The address of the endpoint exposing the email addresses associated with the logged in user. | `GitHubAuthenticationDefaults.UserEmailsEndpoint` |

‎docs/instagram.md

+30
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
# Integrating the Instagram Provider
2+
3+
⚠️ 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.
4+
5+
From [Instagram's documentation](https://developers.facebook.com/docs/instagram-basic-display-api#authentication "Instagram Basic Display API Limitations"):
6+
7+
> 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.
8+
9+
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").
10+
11+
## Example
12+
13+
```csharp
14+
services.AddAuthentication(options => /* Auth configuration */)
15+
.AddInstagram(options =>
16+
{
17+
options.ClientId = "my-client-id";
18+
options.ClientSecret = "my-client-secret";
19+
});
20+
```
21+
22+
## Required Additional Settings
23+
24+
_None._
25+
26+
## Optional Settings
27+
28+
| Property Name | Property Type | Description | Default Value |
29+
|:--|:--|:--|:--|
30+
| `UseSignedRequests` | `bool` | Indicates whether requests to the Instagram API's user information endpoint should be signed. | `false` |

‎docs/linkedin.md

+24
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
# Integrating the LinkedIn Provider
2+
3+
## Example
4+
5+
```csharp
6+
services.AddAuthentication(options => /* Auth configuration */)
7+
.AddLinkedIn(options =>
8+
{
9+
options.ClientId = "my-client-id";
10+
options.ClientSecret = "my-client-secret";
11+
});
12+
```
13+
14+
## Required Additional Settings
15+
16+
_None._
17+
18+
## Optional Settings
19+
20+
| Property Name | Property Type | Description | Default Value |
21+
|:--|:--|:--|:--|
22+
| `EmailAddressEndpoint` | `string` | The address of the endpoint exposing the email addresses associated with the logged in user. | `LinkedInAuthenticationDefaults.EmailAddressEndpoint` |
23+
| `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" ]` |
24+
| `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

+23
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# Integrating the Odnoklassniki Provider
2+
3+
## Example
4+
5+
```csharp
6+
services.AddAuthentication(options => /* Auth configuration */)
7+
.AddOdnoklassniki(options =>
8+
{
9+
options.ClientId = "my-client-id";
10+
options.ClientSecret = "my-client-secret";
11+
});
12+
13+
```
14+
15+
## Required Additional Settings
16+
17+
_None._
18+
19+
## Optional Settings
20+
21+
| Property Name | Property Type | Description | Default Value |
22+
|:--|:--|:--|:--|
23+
| `PublicSecret` | `string?` | The Public App Key from the application registration email. | `null` |

‎docs/okta.md

+23
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# Integrating the Okta Provider
2+
3+
## Example
4+
5+
```csharp
6+
services.AddAuthentication(options => /* Auth configuration */)
7+
.AddOkta(options =>
8+
{
9+
options.ClientId = "my-client-id";
10+
options.ClientSecret = "my-client-secret";
11+
options.Domain = "https://dev-000000.okta.com";
12+
});
13+
```
14+
15+
## Required Additional Settings
16+
17+
| Property Name | Property Type | Description | Default Value |
18+
|:--|:--|:--|:--|
19+
| `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` |
20+
21+
## Optional Settings
22+
23+
_None._

‎docs/patreon.md

+23
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# Integrating the Patreon Provider
2+
3+
## Example
4+
5+
```csharp
6+
services.AddAuthentication(options => /* Auth configuration */)
7+
.AddPatreon(options =>
8+
{
9+
options.ClientId = "my-client-id";
10+
options.ClientSecret = "my-client-secret";
11+
});
12+
```
13+
14+
## Required Additional Settings
15+
16+
_None._
17+
18+
## Optional Settings
19+
20+
| Property Name | Property Type | Description | Default Value |
21+
|:--|:--|:--|:--|
22+
| `Fields` | `ISet<string>` | The list of fields to retrieve from the user information endpoint. | `[ "first_name", "full_name", "last_name", "thumb_url", "url" ]` |
23+
| `Includes` | `ISet<string>` | The list of related data to include from the user information endpoint. | `[]` |

0 commit comments

Comments
 (0)