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

Lines changed: 2 additions & 0 deletions
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

Lines changed: 67 additions & 0 deletions
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

Lines changed: 26 additions & 0 deletions
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

Lines changed: 23 additions & 0 deletions
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

Lines changed: 22 additions & 0 deletions
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

Lines changed: 24 additions & 0 deletions
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

Lines changed: 22 additions & 0 deletions
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

Lines changed: 22 additions & 0 deletions
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

Lines changed: 22 additions & 0 deletions
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

Lines changed: 26 additions & 0 deletions
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` |

0 commit comments

Comments
 (0)