Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update Documentation #87

Merged
merged 1 commit into from
Feb 24, 2022
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 4 additions & 4 deletions docs/Facebook/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,17 +3,17 @@
## Register with Facebook
Start by going to the [Facebook Developer page](https://developers.facebook.com/), and sign-in/register. Then, go to the [Apps page](https://developers.facebook.com/apps/). Click 'Add a New App'. Enter an app 'Display Name' and 'Contact Email', then click 'Create App ID':

![Create the app](https://github.com/vapor-community/Imperial/blob/master/docs/Facebook/create-application.png)
![Create the app](https://github.com/vapor-community/Imperial/blob/main/docs/Facebook/create-application.png)

Select 'Integrate Facebook Login' and click the 'Confirm' button. This will redirect to the 'Settings > Basic' screen where you can find the generated 'App ID' and 'App Secret'. It will also add the 'Facebook Login' Product in the left sidebar. Before the app is live you will need to fill out some of the other fields for privacy and GDPR disclosure.

![App ID and App Secret](https://github.com/vapor-community/Imperial/blob/master/docs/Facebook/application-id.png)
![App ID and App Secret](https://github.com/vapor-community/Imperial/blob/main/docs/Facebook/application-id.png)

In the left sidebar under Products, click 'Facebook Login > Settings'. Enter one or more 'Valid OAuth Redirect URIs'. Ex) https://fancyvapor.app/facebook/callback.

**Note:** Facebook requires https for redirect URIs so you'll need to use https in development and production environments. Setting up https is outside the scope of this tutorial.

![Add Redirect URI](https://github.com/vapor-community/Imperial/blob/master/docs/Facebook/add-redirect-uri.png)
![Add Redirect URI](https://github.com/vapor-community/Imperial/blob/main/docs/Facebook/add-redirect-uri.png)

This provides you with an OAuth Client ID and secret you can provide to Imperial.

Expand All @@ -30,7 +30,7 @@ You can then register the OAuth provider like normal.

With the accessToken your application can now access information about the user. The needs of each application differ so you can test out your implementation using [Facebook's Graph API Explorer](https://developers.facebook.com/tools/explorer/).

![Facebook's Graph API Explorer](https://github.com/vapor-community/Imperial/blob/master/docs/Facebook/facebook-graph-api-explorer.png)
![Facebook's Graph API Explorer](https://github.com/vapor-community/Imperial/blob/main/docs/Facebook/facebook-graph-api-explorer.png)

You can extend `Facebook` to add a `getUserInfo` function to get the user details. Customizing the last part of the `facebookUserAPIURL` will allow you to access the user data needed by your application. Refer to the Graph Explorer for testing what attributes are available. For convenience we decode the response using a small struct called `FacebookUserInfo`.

Expand Down
4 changes: 2 additions & 2 deletions docs/GitHub/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,11 +4,11 @@

Start by going to the [GitHub Developer Program page](https://developer.github.com/program/), and register. Then, go to your Account Settings, then the [Developer Settings](https://github.com/settings/developers). Select 'New OAuth App'. Fill out the information required and register the application:

![Create the app](https://github.com/vapor-community/Imperial/blob/master/docs/GitHub/create-application.png)
![Create the app](https://github.com/vapor-community/Imperial/blob/main/docs/GitHub/create-application.png)

You must also specify a callback URL. Imperial will register a route to this URL to handle the redirect for you:

![The callback path for GitHub OAuth](https://github.com/vapor-community/Imperial/blob/master/docs/GitHub/callback-url.png)
![The callback path for GitHub OAuth](https://github.com/vapor-community/Imperial/blob/main/docs/GitHub/callback-url.png)

This provides you with an OAuth Client ID and secret you can provide to Imperial.

Expand Down
4 changes: 2 additions & 2 deletions docs/Google/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,11 +4,11 @@ We need to start by creating a client ID and secret so Google can identify us. G

Select 'Create credentials' > 'OAuth client ID':

![Create Credentials](https://github.com/vapor-community/Imperial/blob/master/docs/Google/create-oauth-credentials.png?raw=true)
![Create Credentials](https://github.com/vapor-community/Imperial/blob/main/docs/Google/create-oauth-credentials.png?raw=true)

Select 'Web application'. The name that you enter should be the name of your project. Under the 'Restrictions' section, in 'Authorized redirect URIs', you will need to add a URI for Google to redirect to after the authentication is complete. If you are developing locally, it will be `http://localhost:8080/...` or `https...` if you have configured SSL:

![Create Credentials](https://github.com/vapor-community/Imperial/blob/master/docs/Google/configure-app-creds.png?raw=true)
![Create Credentials](https://github.com/vapor-community/Imperial/blob/main/docs/Google/configure-app-creds.png?raw=true)

This provides you with an OAuth Client ID and secret you can provide to Imperial.

Expand Down
12 changes: 6 additions & 6 deletions docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -80,9 +80,9 @@ let protected = routes.grouped(ImperialMiddleware(redirect: "/"))

Below are links to the documentation to setup federated login with various OAuth providers that are supported.

- [GitHub](https://github.com/vapor-community/Imperial/blob/master/docs/GitHub/README.md)
- [Google](https://github.com/vapor-community/Imperial/blob/master/docs/Google/README.md)
- [Shopify](https://github.com/vapor-community/Imperial/blob/master/docs/Shopify/README.md)
- [Facebook](https://github.com/vapor-community/Imperial/tree/master/docs/Facebook/README.md)
- [Keycloak](https://github.com/vapor-community/Imperial/tree/master/docs/Keycloak/README.md)
- [Discord](https://github.com/vapor-community/Imperial/tree/master/docs/Discord/README.md)
- [GitHub](https://github.com/vapor-community/Imperial/blob/main/docs/GitHub/README.md)
- [Google](https://github.com/vapor-community/Imperial/blob/main/docs/Google/README.md)
- [Shopify](https://github.com/vapor-community/Imperial/blob/main/docs/Shopify/README.md)
- [Facebook](https://github.com/vapor-community/Imperial/tree/main/docs/Facebook/README.md)
- [Keycloak](https://github.com/vapor-community/Imperial/tree/main/docs/Keycloak/README.md)
- [Discord](https://github.com/vapor-community/Imperial/tree/main/docs/Discord/README.md)
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

Start by going to the [GitHub Developer Program page](https://developer.github.com/program/), and register. Then, go to your Account Settings, then the [Developer Settings](https://github.com/settings/developers). Select 'New OAuth App'. Fill out the information required and register the application:

![Create the app](https://github.com/vapor-community/Imperial/blob/master/docs/GitHub/create-application.png)
![Create the app](https://github.com/vapor-community/Imperial/blob/main/docs/GitHub/create-application.png)

Now that we have an OAuth application registered with GitHub, we can add Imperial to our project (We will not be going over how to create the project, as I will assume that you have already done that).

Expand Down Expand Up @@ -76,7 +76,7 @@ try router.oAuth(from: GitHub.self, authenticate: "github", callback: "gh-auth-c

The `authenticate` argument is the path you will go to when you want to authenticate the user. The `callback` argument has to be the same path that you entered when you registered your application on GitHub:

![The callback path for GitHub OAuth](https://github.com/vapor-community/Imperial/blob/master/docs/GitHub/callback-url.png)
![The callback path for GitHub OAuth](https://github.com/vapor-community/Imperial/blob/main/docs/GitHub/callback-url.png)

The completion handler is fired when the callback route is called by the OAuth provider. The access token is passed in and a response is returned.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -4,11 +4,11 @@ We need to start by creating a client ID and secret so Google can identify us. G

Select 'Create credentials' > 'OAuth client ID':

![Create Credentials](https://github.com/vapor-community/Imperial/blob/master/docs/Google/create-oauth-credentials.png?raw=true)
![Create Credentials](https://github.com/vapor-community/Imperial/blob/main/docs/Google/create-oauth-credentials.png?raw=true)

Select 'Web application'. The name that you enter should be the name of your project. Under the 'Restrictions' section, in 'Authorized redirect URIs', you will need to add a URI for Google to redirect to after the authentication is complete. If you are developing locally, it will be `http://localhost:8080/...` or `https...` if you have configured SSL:

![Create Credentials](https://github.com/vapor-community/Imperial/blob/master/docs/Google/configure-app-creds.png?raw=true)
![Create Credentials](https://github.com/vapor-community/Imperial/blob/main/docs/Google/configure-app-creds.png?raw=true)

Now that we have the necessary information for Google, we will setup Imperial with our application.

Expand Down Expand Up @@ -82,7 +82,7 @@ try router.oAuth(from: Google.self, authenticate: "google", callback: "http://lo

The `authenticate` argument is the path you will go to when you want to authenticate the user. The `callback` argument has to be the same path that you entered when you registered your application on Google:

![The callback path for Google OAuth](https://github.com/vapor-community/Imperial/blob/master/docs/Google/callback-uri.png?raw=true)
![The callback path for Google OAuth](https://github.com/vapor-community/Imperial/blob/main/docs/Google/callback-uri.png?raw=true)

The completion handler is fired when the callback route is called by the OAuth provider. The access token is passed in and a response is returned.

Expand Down
4 changes: 2 additions & 2 deletions docs/docsets/.docset/Contents/Resources/Documents/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,5 +2,5 @@

Below are links to the documentation to setup federated login with various OAuth providers that are supported.

- [GitHub](https://github.com/vapor-community/Imperial/blob/master/docs/GitHub/README.md)
- [Google](https://github.com/vapor-community/Imperial/blob/master/docs/Google/README.md)
- [GitHub](https://github.com/vapor-community/Imperial/blob/main/docs/GitHub/README.md)
- [Google](https://github.com/vapor-community/Imperial/blob/main/docs/Google/README.md)
4 changes: 2 additions & 2 deletions docs/docsets/.docset/Contents/Resources/Documents/index.html
Original file line number Diff line number Diff line change
Expand Up @@ -134,14 +134,14 @@ <h1 id='imperial' class='heading'>Imperial</h1>
<p>Imperial is a Federated Login service, allowing you to easily integrate your Vapor applications with OAuth providers to handle your apps authentication.</p>

<ul>
<li><a href="https://github.com/vapor-community/Imperial/blob/master/docs">Usage Guides</a></li>
<li><a href="https://github.com/vapor-community/Imperial/blob/main/docs">Usage Guides</a></li>
</ul>
<h2 id='attribution' class='heading'>Attribution</h2>

<p>Author(s): @calebkleveter</p>
<h2 id='license' class='heading'>License</h2>

<p>All code contained in the Imperial package is under the <a href="https://github.com/vapor-community/Imperial/blob/master/LICENSE">MIT</a> license agreement.</p>
<p>All code contained in the Imperial package is under the <a href="https://github.com/vapor-community/Imperial/blob/main/LICENSE">MIT</a> license agreement.</p>

</section>
</section>
Expand Down
4 changes: 2 additions & 2 deletions docs/index.html
Original file line number Diff line number Diff line change
Expand Up @@ -134,14 +134,14 @@ <h1 id='imperial' class='heading'>Imperial</h1>
<p>Imperial is a Federated Login service, allowing you to easily integrate your Vapor applications with OAuth providers to handle your apps authentication.</p>

<ul>
<li><a href="https://github.com/vapor-community/Imperial/blob/master/docs">Usage Guides</a></li>
<li><a href="https://github.com/vapor-community/Imperial/blob/main/docs">Usage Guides</a></li>
</ul>
<h2 id='attribution' class='heading'>Attribution</h2>

<p>Author(s): @calebkleveter</p>
<h2 id='license' class='heading'>License</h2>

<p>All code contained in the Imperial package is under the <a href="https://github.com/vapor-community/Imperial/blob/master/LICENSE">MIT</a> license agreement.</p>
<p>All code contained in the Imperial package is under the <a href="https://github.com/vapor-community/Imperial/blob/main/LICENSE">MIT</a> license agreement.</p>

</section>
</section>
Expand Down