Skip to content

Commit

Permalink
Edits and clarifications to the Facebook readme and tutorial.
Browse files Browse the repository at this point in the history
  • Loading branch information
@natebird
natebird committed Jan 22, 2019
1 parent b797621 commit bcdce3b
Showing 1 changed file with 22 additions and 24 deletions.
46 changes: 22 additions & 24 deletions docs/Facebook/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,24 +2,26 @@

1. [Register with Facebook](#register-with-facebook)
2. [Add Imperial to Vapor App](#add-imperial-to-vapor-app)
3. [Configuring Imperial](#configuring-imperial)
4. [Protecting Routes](#protecting-routes)

## 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 and click Create App ID:
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)

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

In the left sidebar under Products, Click, Facebook Login > Settings. Enter one or more Valid OAuth Redirect URIs. Ex) https://fancyvapor.app/facebook/callback.
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 it on your development machine as well.
**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 Imperial to Vapor App
Now that the OAuth application registered with Facebook, we can add Imperial to our project. This tutorial will not cover how to create the project. It is assumed that step was already completed.
Now that the application is registered with Facebook, we can add Imperial to our Vapor project. Creating and setting up a Vapor project is outside the scope of this tutorial.

Add the following line of code to your `dependencies` array in your package manifest file:

Expand All @@ -29,16 +31,16 @@ Add the following line of code to your `dependencies` array in your package mani

**Note:** There might be a later version of the package available, in which case you will want to use that version.

You will also need to add the package as a dependency for the targets you will be using it in:
Also, add the package as a dependency for the targets where it will be used:

```swift
.target(name: "App", dependencies: ["Vapor", "Imperial"],
exclude: ["Config", "Database", "Public", "Resources"]),
```

Then run `vapor update` or `swift package update`. Make sure you regenerate your Xcode project (`vapor xcode`) if you are using Xcode.
Then run `vapor update` to fetch the Imperial package. Make sure to also regenerate your Xcode project (`vapor xcode`) if you are using Xcode.

Now that Imperial is installed, we need to add `middlewares.use(SessionsMiddleware.self)` to our middleware configuration in the `configure.swift` file:
Now that Imperial is installed, we need to add `middlewares.use(SessionsMiddleware.self)` to our middleware configuration in the `configure.swift` file. Remember to import the Imperial package as well.

```swift
import Imperial
Expand All @@ -57,17 +59,20 @@ public func configure(_ config: inout Config, _ env: inout Environment, _ servic
}
```

If you Build (`vapor build`) and Run (`vapor run`) your app and you are using a database, you will probably get an error similar to below:
Now, if you build and run (`vapor build && run`) your app and you are using a database, you may see a KeyedCache ambiguity error similar to below:

```
⚠️ [ServiceError.ambiguity: Please choose which KeyedCache you prefer, multiple are available: MemoryKeyedCache, FluentCache<SQLiteDatabase>.] [Suggested fixes: `config.prefer(MemoryKeyedCache.self, for: KeyedCache.self)`. `config.prefer(FluentCache<SQLiteDatabase>.self, for: KeyedCache.self)`.]
```

Just pick one of the listed suggestions and place it at the top of your `configure` function. If you want your data to persist across server reboots, use `config.prefer(FluentCache<SQLiteDatabase>.self, for: KeyedCache.self)`

Imperial needs the client id and secret to authenticate with Facebook. To allow Imperial access to these tokens, you will need to set the environment variables, `FACEBOOK_CLIENT_ID` and `FACEBOOK_CLIENT_SECRET` from values found on the Facebook Settings page described above.

Now, all we need to do is register the GitHub service in your main router method, like this:
## Configuring Imperial

Imperial needs the client id and secret to authenticate with Facebook. To allow Imperial access to these tokens, you will need to set the environment variables, `FACEBOOK_CLIENT_ID` and `FACEBOOK_CLIENT_SECRET` using the respective values found on the Facebook settings page described above.

Now, all you need to do is register the Facebook authentication route in your main router method (for instance, in `configure.swift`):

```swift
try router.oAuth(from: Facebook.self, authenticate: "facebook", callback: "https://fancyvapor.app/facebook/callback") { (request, token) in
Expand All @@ -76,22 +81,13 @@ try router.oAuth(from: Facebook.self, authenticate: "facebook", callback: "https
}
```

If you just want to redirect, without doing anything else in the callback, you can use the helper `Route.oAuth` method that takes in a redirect string:

```swift
import Imperial
//...

try router.oAuth(from: Facebook.self, authenticate: "facebook", callback: "https://fancyvapor.app/facebook/callback", redirect: "/")
```

The `authenticate` argument is the path you will go to when you want to authenticate the user. In the example above, `https://fancyvapor.app/facebook` would redirect the user to Facebook for authentication using the the required app id, secret, and redirect URI. Facebook will then validate the request and match the `callback` (redirect) URI to what was provided during registration.
The `authenticate` argument is the relative path you will go to when you want to authenticate with Facebook. Therefore, "facebook" would equal a full URL of `https://fancyvapor.app/facebook`. Visiting this URL will trigger Imperial to redirect to Facebook for authentication using the required parameters. Facebook will then validate the request and match the `callback` URI to the 'Valid OAuth Redirect URI' provided during registration.

Therefore, the `callback` argument needs to match one of the Valid OAuth Redirect URI entered in the Facebook app settings:
Therefore, the `callback` argument needs to match one of the 'Valid OAuth Redirect URI' entered in the Facebook app settings:

![The callback path for Facebook App](https://github.com/vapor-community/Imperial/blob/master/docs/GitHub/add-redirect-uri.png)
![The callback path for Facebook App](https://github.com/vapor-community/Imperial/blob/master/docs/Facebook/add-redirect-uri.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.
The completion handler is fired when the callback route is called by the OAuth provider (Facebook). The access token is passed in and a response is returned.

The `access_token` is available within a route through an Imperial helper method for the `Request` type:

Expand All @@ -102,6 +98,8 @@ import Imperial
let token = try request.accessToken()
```

## Protecting Routes

Now that you are authenticating the user, you will want to protect certain routes to make sure the user is authenticated. You can do this by adding the `ImperialMiddleware` to a router group (or maybe your middleware config):

```swift
Expand Down

0 comments on commit bcdce3b

Please sign in to comment.