README

Laravel One Time Code Authentication allow you to send by mail an one time code to auth your users.

Installation

You can install the package via composer:

composer require coucounco/laravel-otc

Run the installer

php artisan otc:install

Configuration

Edit config/otc.php

return [
    'notifier_class' => \Illuminate\Support\Facades\Notification::class,
    'notification_class' => \coucounco\LaravelOtc\Notifications\OneTimeCodeNotification::class,

    'authenticatables' => [
        'user' => [
            'model' => \App\Models\User::class,
            'identifier' => 'email',
        ]
    ]
];

notifier_class

Define what class will be called to send the notification. By default it use the Notification facade of Laravel.

'notifier_class' => \Illuminate\Support\Facades\Notification::class,

notification_class

Define what notification will be sent.

'notification_class' => \coucounco\LaravelOtc\Notifications\OneTimeCodeNotification::class,

You can replace this class by any other notification, you will recieve a OtcToken $token as constructor parameters

public function __construct(OtcToken $token) {
    $this->token = $token;
}

You can access the code that need to be sent from the $token variable

$token->code

authenticatables

This array will define a list of entites that can be used to get authentified. It's like a simplified version of laravel guard. I might move this to guard in the futur. The main goal is to set what model and what column are used to find the model in the database.

user is the name of the "guard"/type
model is the corresponding eloquent model
identifier is the identifier column that will be used to find the corresponding user

'user' => [
    'model' => \App\Models\User::class,
    'identifier' => 'email',
]

Usage

Check

Check if the user is authenticated

Otc::check()

This method will return true or false.

If the user is not authentified you can return an error

if(!Otc::check()) {
    return Otc::unauthorizedResponse($user);
}

This response will return 401 http error with the following body.

{
    "request_code_url": ".../vendor/coucounco/laravel-otc/auth/request-code",
    "request_code_body": {
        "type": "user",
        "identifier": "test@test.com"
    }
}

You must use the request_code_url as the url to request a code (ye seem obvious) and you must pass the request_code_body as the body in json format !

Request a code

Send a post request

POST /vendor/coucounco/laravel-otc/auth/request-code

with body

{
    "type": "user",
    "identifier": "test@test.com"
}

You need to send the type and the identifier of your authenticatables entity

An email will be sent to the corresponding entity if available. The email will contain the code.

Request a token

Send a post request

POST /vendor/coucounco/laravel-otc/auth/code

with body

{
    "type": "user",
    "identifier": "test@test.com",
    "code": <code>
}

You need to send the code that should have been retrieved from the user through a form or anything else.

You will recieve a token back

{
    "token": "9vov6FjW47v6JjH...4iPzPH0PwpwdE"
}

And you can use this token for every further request.

Authentified request

When you have the token, you can send it with you request to be authentified.

Pass it in the headers

Authorization: Bearer <token>

Or in the query string

?token=<token>

Troubleshooting

CORS

If you use fruitcake/laravel-cors to manage CORS in your app. You will get CORS error when doing call to this package endpoints.

You will need to add a new path in your config/cors.php in the paths array

    'paths' => [
        // ...
        'vendor/coucounco/laravel-otc/*',
    ],

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security related issues, please use the issue tracker.

Credits

License

The MIT License (MIT). Please see License File for more information.

coucounco / laravel-otc

Maintainers

Details