https://github.com/rluders/wn-jwtauth-plugin
JWTAuth Plugin for WinterCMS
https://github.com/rluders/wn-jwtauth-plugin
hacktoberfest jwt jwt-authentication jwtauth token token-authentication wintercms wintercms-plugin
Last synced: 7 days ago
JSON representation
JWTAuth Plugin for WinterCMS
- Host: GitHub
- URL: https://github.com/rluders/wn-jwtauth-plugin
- Owner: rluders
- License: gpl-3.0
- Created: 2018-08-18T08:31:33.000Z (almost 8 years ago)
- Default Branch: main
- Last Pushed: 2026-05-16T05:30:28.000Z (16 days ago)
- Last Synced: 2026-05-16T07:21:29.668Z (15 days ago)
- Topics: hacktoberfest, jwt, jwt-authentication, jwtauth, token, token-authentication, wintercms, wintercms-plugin
- Language: PHP
- Homepage:
- Size: 185 KB
- Stars: 30
- Watchers: 3
- Forks: 29
- Open Issues: 10
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
# Introduction
This plugin provides a JSON Web Tokens authentication mechanism for [Winter CMS](http://www.wintercms.com) integrated with `Winter.User`. It's essential for your web application built with Angular, Vue.js, React or other modern Javascript frameworks.
## Requirements
- PHP 8.1+
- WinterCMS 1.2+ (Laravel 9) or 1.3+ (Laravel 10)
- [Winter.User](https://github.com/wintercms/wn-user-plugin) plugin `^2.0`
- [RLuders.CORS](https://wintercms.com/plugin/rluders-cors) plugin (optional, but recommended)
## Theme
- [Angular Skeleton](https://wintercms.com/theme/rluders-angular2)
## Tutorials
- [Creating Vue, Vuex and Winter CMS APP - Login and Register](https://www.youtube.com/watch?v=8S3DySmMOuk) by [Watch and Learn](https://www.youtube.com/channel/UCXQC_GB5hG6PkzIhSMZ-hWA)
# Installation
```sh
$ composer require rluders/jwtauth
```
# Configuration
You must set a secret token for your application. Do do it, on Winter's Backend access: _Settings > Users > JWTAuth_
# Usage
Here's the list of available endpoints for this plugin.
> If you are using [**Postman**](https://www.getpostman.com/), you can [click here to import the collection](https://www.getpostman.com/collections/5667c055f6f81ff3f821) with all the calls that you need to test it.
## Login
`POST /api/auth/login`
**Route name**
`api.auth.login`
### Parameters
| Name | Type | Required | Description |
| -------- | ------ | -------- | ----------------------- |
| login | string | Yes | Account login attribute |
| password | string | Yes | Account password |
> The field `login` value can be the account `email` or `username`. You can select it on `Winter.User` configuration what field should be used for login.
### Responses
**SUCCESS**
> Code: 200
```json
{
"token": string,
"user": object
}
```
**ERROR**
> Code: 401
```json
{
"error":
invalid_credentials |
could_not_create_token |
user_inactive |
user_is_banned
}
```
## Register
`POST /api/auth/register`
**Route name**
`api.auth.register`
### Parameters
| Name | Type | Required | Description |
| --------------------- | ------ | -------- | ------------------------ |
| username | string | No | Account username |
| email | string | Yes | Account email |
| password | string | Yes | Account password |
| password_confirmation | string | No | Confirm the new password |
> The field `username` can be **required**. It depends of your `Winter.User` configuration.
### Responses
**SUCCESS**
> Code: 201
```json
[]
```
**ERROR**
> Code: 401
```json
{
"error": object | registration_disabled
}
```
### Supported events
- `Winter.User.beforeRegister`
- `Winter.User.register`
## Account Activation
`POST /api/auth/account-activation`
**Route name**
`api.auth.account-activation`
### Parameters
| Name | Type | Required | Description |
| --------------- | ------ | -------- | ----------------------- |
| activation_code | string | Yes | Account activation code |
### Responses
**SUCCESS**
> Code: 200
```json
[]
```
**ERROR**
> Code: 422
```json
{
"error": invalid_activation_code | invalid_user | user_not_found
}
```
## Forgot Password
`POST /api/auth/forgot-password`
**Route name**
`api.auth.forgot-password`
### Parameters
| Name | Type | Required | Description |
| ----- | ------ | -------- | ------------- |
| email | string | Yes | Account email |
### Responses
**SUCCESS**
> Code: 200
```json
[]
```
**ERROR**
> Code: 404
```json
{
"error": user_not_found
}
```
## Reset Password
`POST /api/auth/reset-password`
**Route name**
`api.auth.reset-password`
### Parameters
| Name | Type | Required | Description |
| --------------------- | ------ | -------- | ------------------------ |
| reset_password_code | string | Yes | Reset password code |
| password | string | Yes | Account new password |
| password_confirmation | string | No | Confirm the new password |
### Responses
**SUCCESS**
> Code: 200
```json
[]
```
**ERROR**
> Code: 422
```json
{
"error":
invalid_reset_password_code | invalid_user | invalid_reset_password_code
}
```
## Refresh Token
`POST /api/auth/refresh-token`
**Route name**
`auth.api.refresh-token`
### Parameters
| Name | Type | Required | Description |
| ----- | ------ | -------- | ------------------ |
| token | string | Yes | Valid user JWToken |
### Responses
**SUCCESS**
> Code: 200
```json
{
"token": string
}
```
**ERROR**
> Code: 403
```json
{
"error": could_not_refresh_token | given_token_was_blacklisted
}
```
## Get User
`GET /api/auth/me`
**Middleware**
`jwt.auth`
**Route name**
`api.auth.me`
### Parameters
| Name | Type | Required | Description |
| ----- | ------ | -------- | ----------- |
| token | string | Yes | Valid token |
### Responses
**SUCCESS**
> Code: 200
```json
{
"user": object
}
```
**ERROR**
> Code: 404
```json
{
"error": user_not_found
}
```
## Logout
`POST /api/auth/logout`
**Middleware**
`jwt.auth`
**Route name**
`api.auth.logout`
Invalidates (blacklists) the current JWT. The token cannot be used again.
### Responses
**SUCCESS**
> Code: 204 No Content
**ERROR**
> Code: 401 — Missing or invalid token
---
# Advanced
## Custom JWT Claims
Other plugins can add custom claims to the JWT by listening to the `rluders.jwtauth.customClaims` event.
The listener receives `(&$claims, $user)` — modify the `$claims` array by reference.
```php
// In another plugin's boot() method
Event::listen('rluders.jwtauth.customClaims', function (&$claims, $user) {
$claims['role'] = $user->role;
$claims['org'] = $user->organisation_id;
});
```
## OpenAPI / Swagger Spec
A machine-readable API spec is available at [openapi.yaml](openapi.yaml).
Import it into Postman, Insomnia, Swagger UI, or any OpenAPI-compatible tooling.
## Testing
Requires [Podman](https://podman.io/) or Docker.
```bash
# Build test image and run the full test suite
make test
# Unit tests only
make test-unit
# Feature tests only
make test-feature
# Drop into the container shell for debugging
make shell
```
See [CONTRIBUTING.md](CONTRIBUTING.md) for the commit convention and PR workflow.
---
# Known issues
Beside the fact that I'm always trying to solve the possible issues, bad things could happen. Here, an list of possible issues and how to fix it.
## Note to Apache users
In order to use the authorization Bearer Token you must add the following code to your `.httaccess`
```
RewriteEngine On
RewriteCond %{HTTP:Authorization} ^(.*)
RewriteRule .* - [e=HTTP_AUTHORIZATION:%1]
```
# License
GPLv3