https://github.com/eidng8/lumen-auth-app
A simple trial with lumen to build an authorization micro service
https://github.com/eidng8/lumen-auth-app
jwt lumen microservice
Last synced: 12 months ago
JSON representation
A simple trial with lumen to build an authorization micro service
- Host: GitHub
- URL: https://github.com/eidng8/lumen-auth-app
- Owner: eidng8
- License: gpl-3.0
- Created: 2021-01-06T08:36:29.000Z (about 5 years ago)
- Default Branch: master
- Last Pushed: 2023-04-19T20:28:59.000Z (almost 3 years ago)
- Last Synced: 2025-02-13T15:34:35.505Z (about 1 year ago)
- Topics: jwt, lumen, microservice
- Language: PHP
- Homepage:
- Size: 446 KB
- Stars: 0
- Watchers: 2
- Forks: 0
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# JWT authorization microservice using Lumen
[](https://www.php.net/releases/8.0/en.php)
[](/LICENSE)
[](https://github.com/eidng8/lumen-auth-app/actions)
[](https://travis-ci.com/github/eidng8/lumen-auth-app)
[](https://github.styleci.io/repos/327249822)
[](https://codecov.io/gh/eidng8/lumen-auth-app)
[](https://codeclimate.com/github/eidng8/lumen-auth-app)
## Purpose
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.
## Features
This package is built using [jwt-auth](https://github.com/tymondesigns/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`.
## Configurations
Two configuration has been added to `config/jwt.php`.
### `issuer`
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.
### `accepted_issuers`
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.
## List of end points
### `/register`
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.
#### Request parameters
```json
{
"name": "new-user",
"email": "some.one@example.com",
"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.
#### Success response
```json
{
"user": {
"name": "test-user1",
"email": "someone1@example.com",
"updated_at": "2021-01-07T10:32:49.000000Z",
"created_at": "2021-01-07T10:32:49.000000Z",
"id": 230
},
"message": "User has been successfully created."
}
```
#### Customization
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()`.
### `/login`
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.
#### Request parameters
```json
{
"email": "some.one@example.com",
"password": "just a password"
}
```
#### Success response
```json
{
"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.
#### Customization
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.
### `/password/reset`
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.
#### Request parameters
```json
{
"email": "some.one@example.com"
}
```
#### Success response
```json
{
"message": "Password reset email has been sent to your email."
}
```
#### Customization
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.
### `/refresh`
Declared in `App\Http\Controllers\Token\Controller::refresh()`.
Refresh a token. The authorization header is required. There is no request body.
#### Request parameters
##### HTTP header
```text
Authorization: bearer JWT_token
```
#### Success response
```json
{
"token": "the newly generated JWT token",
"token_type": "bearer",
"expires_in": 3600
}
```
### `/logout`
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.
#### Request parameters
##### HTTP header
```text
Authorization: bearer JWT_token
```
#### Success response
```json
{
"message": "See you soon."
}
```
### `/verify`
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.
#### Request parameters
##### HTTP header
```text
Authorization: bearer JWT_token
```
#### Success response
```json
{
"ttl": 3600
}
```
### `/heartbeat`
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.
#### Request parameters
##### HTTP header
```text
Authorization: bearer JWT_token
```
#### Success response
```json
{
"time": "2021-01-10T03:45:27+00:00"
}
```