This is a trial project to build an authorization service using Lumen that provides minimum functionalities. Although this is a trial project, I hope to make it suitable for later (or others) use as boilerplate or foundation for production projects or products. By production, it isn't mean this bare-bone JWT token could be used directly, as JWT is only a token format. Extra consideration should be taken beforehand, such as using protocols such as OAuth.
This package is built using jwt-auth
to provide authentication & JWT authorization service. It only supports HTTP
authorization header with JWT tokens, and the token type must be bearer.
The database consists of a minimum set of columns, including user credentials.
Other user properties are expected to be handled by separate service rather than
this one. To expand the data scope, one has to amend database migration
and AuthController.
Two configuration has been added to config/jwt.php.
This is the preferred value to the iss claim of all tokens generated by the
/login end point. The corresponding JWT_ISSUER key has been added to .env
file.
A list of issuers to be accepted by authorization end points. The corresponding
JWT_ACCEPTED_ISSUERS key has been added to .env file. It holds a comma
separated list.
Declared in App\Http\Controllers\AuthController::register().
Creates a new user. Parameters include name, email, and password with
confirmation. Do not provide authorization header to this end point.
{
"name": "new-user",
"email": "[email protected]",
"password": "just a password",
"password_confirmation": "just a password"
}All these fields are required, and the password and password_confirmation
must be identical. Although this is a JSON end point, it accepts good old form
data too. Upon success, it returns some information about the created record.
{
"user": {
"name": "test-user1",
"email": "[email protected]",
"updated_at": "2021-01-07T10:32:49.000000Z",
"created_at": "2021-01-07T10:32:49.000000Z",
"id": 230
},
"message": "User has been successfully created."
}To expand or change registration information, such as adding phone number. One
has to first add the phone number to database migration, update validation rules
and the User model creation inside AuthController::register().
Declared in App\Http\Controllers\AuthController::login().
Checks the provided credentials and generates a JWT token if the credentials are valid. Do not provide authorization header to this end point.
{
"email": "[email protected]",
"password": "just a password"
}{
"token": "the newly generated JWT token",
"token_type": "bearer",
"expires_in": 3600
}Please note that the token_type will always be "bearer", and expires_in is
in seconds. As mentioned above, when using this token, the type of the HTTP
authorization header must be bearer. e.g. Authorization: bearer JWT_token.
In real world cases, the token_type field may not be necessary, because the
bearer type is most like the expected value. It is provided here only for
emphasis.
To change the login field, say using phone number instead of email. Beside
modifications mentioned in registration customization, one has to change the
AuthController::login() method to use the new identify field.
Declared in App\Http\Controllers\AuthController::passwordReset().
Starts the password reset flow. This is a scaffold end point, which doesn't contain any actual logic.
{
"email": "[email protected]"
}{
"message": "Password reset email has been sent to your email."
}Password reset could take various forms in real world applications. Here we just demonstrate the first step of reset process using email. One could simply utilize Laravel reset password flow, or design custom process flow.
Declared in App\Http\Controllers\Token\Controller::refresh().
Refresh a token. The authorization header is required. There is no request body.
Authorization: bearer JWT_token
{
"token": "the newly generated JWT token",
"token_type": "bearer",
"expires_in": 3600
}Declared in App\Http\Controllers\Token\Controller::logout().
Logout the token, rendering it invalid for further use. The authorization header is required. There is no request body.
Authorization: bearer JWT_token
{
"message": "See you soon."
}Declared in App\Http\Controllers\Token\Controller::verify().
Validates the token and returns its TTL if it's valid. This is just a scaffold, feel free to implement whatever suitable.
Authorization: bearer JWT_token
{
"ttl": 3600
}Declared in App\Http\Controllers\Token\Controller::heartbeat().
Returns the current server time in W3C format. This is just a scaffold, feel free to implement whatever suitable.
Authorization: bearer JWT_token
{
"time": "2021-01-10T03:45:27+00:00"
}