

# Getting Started

Vapor's Auth Provider package makes implementing authentication and authorization easy and secure. It supports common auth patterns such as:

- Token (bearer) authentication
- Username + password (basic) authentication
- Permission-based authorization
- Session-based persistance

Auth's modular, protocol-based nature also makes it a great foundation for custom auth needs.

Tip

Use `vapor new <name> --template=vapor/auth-template` to create a new project template with AuthProvider and samples included.

## Package

To use Auth, you will need to have the Auth Provider added to your project. This is as simple as adding the following line to your `Package.swift` file.

    .Package(url: "https://github.com/vapor/auth-provider.git", ...)

Check out the Package section for more information.

## Example

Let's take a look at how we can implement a simple, token-based authentication system using Vapor and Auth.

### User

We will start by creating a model to represent our user. If you already have a user class, you can skip this step.

    import Vapor
    import FluentProvider

    final class ExampleUser: Model {
        let name: String

        ...
    }

    extension ExampleUser: Preparation { ... }

Here we create a very simple user with just one property: a name.

Seealso

We're omitting most of `Model` and `Preparation` protocol requirements. Check out Fluent's Getting Started for more information about these protocols.

### Token

Next let's create a model to represent our authentication tokens. These will be stored in a separate database table or collection called "tokens".

When a user logs in, we will create a new token for them. They will then use this token on subsequent requests instead of their username and password.

For now, here's what our simple token model will look like.

    import Vapor
    import FluentProvider

    final class ExampleToken: Model {
        let token: String
        let userId: Identifier

        var user: Parent<ExampleToken, ExampleUser> {
            return parent(id: userId)
        }

        ...
    }

    extension ExampleToken: Preparation { ... }

This token has two properties:

- token: a unique, random string that we will send in requests
- userId: the identifier for the user to whom this token belongs

Seealso

We're using Fluent relations here. Check out Fluent's Relations section for more information.

### Token Authenticatable

Now that we have our example user and token, we can make our user authenticatable with the token.

This might sound complicated, but it's actually pretty easy:

    import AuthProvider

    extension ExampleUser: TokenAuthenticatable {
        // the token model that should be queried
        // to authenticate this user
        public typealias TokenType = ExampleToken
    }

Now that our example user is `TokenAuthenticatable`, we can move on to the next step!

### User Helper

Let's add a simple convenience method on request for accessing the authenticated user.

    extension Request {
        func user() throws -> ExampleUser {
            return try auth.assertAuthenticated()
        }
    }

This is a nice shortcut that will come in handy in a few steps.

### Middleware

To require authentication we need to add the `TokenAuthenticationMiddleware`. You can apply this middleware to individual routes or to the entire Droplet. For simplicity, we'll apply it to the Droplet.

    import Vapor
    import AuthProvider
    import FluentProvider

    let config = try Config()

    config.preparations.append(ExampleUser.self)
    config.preparations.append(ExampleToken.self)

    let drop = try Droplet(config)

    let tokenMiddleware = TokenAuthenticationMiddleware(ExampleUser.self)

    /// use this route group for protected routes
    let authed = drop.grouped(tokenMiddleware)

Since our `ExampleUser` class is `TokenAuthenticatable`, we can pass it into the middleware's init method.

Seealso

If you only want to require authentication for certain routes, look at our Route Group section in the routing docs.

### Route

Now that we have a route group protected by our TokenMiddleware, let's add a route to return the authenticated user's name.

    authed.get("me") { req in
        // return the authenticated user's name
        return try req.user().name
    }

Tip

We're using the `.user()` convenience we added to `Request` here. It is a shortcut for `let user = try req.auth.assertAuthenticated(ExampleUser.self)`

### Database

That's it! We now have a functioning authentication system. Let's add a couple of entries to our database and test it out.

#### Users

id | name
--- | ---
1 | Bob

#### Tokens

id | token | user_id
--- | --- | ---
1 | foo | 1

### Request

Now we can make a request to our Vapor app.

    GET /me HTTP/1.1
    Authorization: Bearer foo

And we should get a response like.

    HTTP/1.1 200 OK
    Content-Type: text/plain

    Bob

#### Bad Token

To make sure it's secure, let's test using a token that's not in our database.

    GET /me HTTP/1.1
    Authorization: Bearer not-a-token

And we should get a response like.

    HTTP/1.1 403 Forbidden

### Next Steps

To build this out into a production-ready authentication system, you will need to build some additional routes for creating users and creating tokens.

Continue on in the Auth section to learn more about different types of authentication.