# Authentication

Masonite makes authentication really simply.

## Authentication Scaffold Command

Masonite comes with a command to scaffold out a basic authentication system. You may use this as a great starting point for adding authentication to your application. This command will create controllers, views, and mailables for you.

**If you would like to implement your own authentication from scratch you can skip to the sections below.**

First run the command to add the news files:

```python
python craft auth
```

Then add the authentication routes to your routes file:

```python
from masonite.authentication import Auth

ROUTES = [
  # routes
]

ROUTES += Auth.routes()
```

You may then go to the `/login` or `/register` route to implement your authentication.

## Configuration

The configuration for Masonite's authentication is quite simple:

```python
from app.User import User

GUARDS = {
    "default": "web",
    "web": {"model": User},
    "password_reset_table": "password_resets",
    "password_reset_expiration": 1440,  # in minutes. 24 hours. None if disabled
}
```

The default key here is the guard to use for authentication. The `web` dictionary is the configuration for the web guard.

## Login Attempts

You can attempt a login by using the `Auth` class and using the `attempt` method:

```python
from masonite.authentication import Auth
from masonite.request import Request

def login(self, auth: Auth, request: Request):
  user = auth.attempt(request.input('email'), request.input("password"))
```

If the attempt succeeds, the user will now be authenticated and the result of the attempt will be the authenticated model.

If the attempt fails then the result will be `None`.

If you know the primary key of the model, you can attempt by the id:

```python
from masonite.authentication import Auth
from masonite.request import Request

def login(self, auth: Auth, request: Request):
  user = auth.attempt_by_id(1)
```

You can logout the current user:

```python
from masonite.authentication import Auth
from masonite.request import Request

def logout(self, auth: Auth):
  user = auth.logout()
```

## User

You can get the current authenticated user:

```python
from masonite.authentication import Auth
from masonite.request import Request

def login(self, auth: Auth, request: Request):
  user = auth.user() #== <app.User.User>
```

If the user is not authenticated, this will return `None`.

## Routes

You can register several routes quickly using the auth class:

```python
from masonite.authentication import Auth

ROUTES = [
  #..
]

ROUTES += Auth.routes()
```

This will register the following routes:

| URI                    | Description                                             |
| ---------------------- | ------------------------------------------------------- |
| GET /login             | Displays a login form for the user                      |
| POST /login            | Attempts a login for the user                           |
| GET /home              | A home page for the user after a login attempt succeeds |
| GET /register          | Displays a registration form for the user               |
| POST /register         | Saved the posted information and creates a new user     |
| GET /password\_reset   | Displays a password reset form                          |
| POST /password\_reset  | Attempts to reset the users password                    |
| GET /change\_password  | Displays a form to request a new password               |
| POST /change\_password | Requests a new password                                 |

## Guards

Guards are encapsulated logic for logging in, registering and fetching users. The web guard uses a `cookie` driver which sets a `token` cookie which is used later to fetch the user.

You can switch the guard on the fly to attempt authentication on different guards:

```python
from masonite.authentication import Auth
from masonite.request import Request

def login(self, auth: Auth, request: Request):
  user = auth.guard("custom").attempt(request.input('email'), request.input("password")) #== <app.User.User>
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.masoniteproject.com/features/authentication.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.