This plugin provides a JSON Web Tokens authentication mechanism for OctoberCMS integrated with RainLab.User. It's essential for your web application built with Angular, Vue.js, React, or other modern Javascript frameworks.
NOTICE: It the last update adds the support to Laravel 6
Requirements
- RainLab.User plugin
- RLuders.CORS plugin (optional, but recommended)
Theme
Tutorials
The following plugin is required
This plugin is also included into the following bundle
The following plugin extends or depends on the plugin
Configuration
You must set a secret token for your application accessing, on October's Backend: Settings > Users > JWTAuth
Usage
Here's the list of available endpoints for this plugin.
If you are using Postman, you can click here to import the collection 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 accountusername
. You can select it onRainLab.User
configuration what field should be used for login.
Responses
SUCCESS
Code: 200
{
token: (string),
user: (object)
}
ERROR
Code: 401
{
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 |
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 on yourRainLab.User
configuration. If you sent other fields that your User model have, it will be saved too.
Responses
SUCCESS
Code: 201
[]
ERROR
Code: 401
{
error: (object|registration_disabled)
}
Supported events
rainlab.user.beforeRegister
rainlab.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
[]
ERROR
Code: 422
{
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 |
---|---|---|---|
string | Yes | Account email |
Responses
SUCCESS
Code: 200
[]
ERROR
Code: 404
{
error: (user_not_found)
}
Reset Password
POST /api/auth/reset-password
Route name
api.auth.reset-password
Parameters
Name | Type | Required | Description |
---|---|---|---|
code | string | Yes | Reset password code |
password | string | Yes | Account new password |
password_confirmation | string | No | Confirm the new password |
Responses
SUCCESS
Code: 200
[]
ERROR
Code: 422
{
error: (invalid_reset_password_code|invalid_user|invalid_reset_password_code)
}
Refresh Token
PATCH /api/auth/refresh-token
Middleware
jwt.auth
Route name
auth.api.refresh-token
Responses
SUCCESS
Code: 200
{
token: (string)
}
ERROR
Code: 403
{
error: (could_not_refresh_token|given_token_was_blacklisted)
}
Get User
PATCH /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
{
user: (object)
}
ERROR
Code: 404
{
error: (user_not_found)
}
Known issues
If you are using the API Generator Plugin you could have some issues. So, for now, you can not use them in the same project.
Requests and Bugs
Did I miss anything?
If you need an additional feature or find a bug, please use the product support forum.
-
Arstan
Found the plugin useful on 11 Mar, 2019
A very useful plugin, but during installation it gives an error, I really hope it will be fixed. Displays an error: "Parse error: syntax error, unexpected '|', expecting variable (T_VARIABLE)" on line 1002 of /var/www/apartment/www/plugins/rluders/jwtauth/vendor/nesbot/carbon/src/Carbon/Traits/Date.php Perhaps this is a mistake on my side, I do not know.
-
Ricardo Lüders author
Replied on 11 Mar, 2019
Hi, Arstan.
Not really a review, but... thanks anyway. In this case, I'm already awared about the issue, as you can see here: https://github.com/rluders/oc-jwtauth-plugin/issues/22
I'm working to solve the issue ASAP. I'll try something during this week.
Thank you.
-
Bhargav
Found the plugin useful on 7 Jun, 2018
Great Plugin, Saved me a lot of time.
Ricardo is very helpful, With updates and troubleshooting.
-
Chris
Found the plugin useful on 21 Nov, 2017
JWTAuth is a great plugin! Ricardo help me a lot when I message to him.
-
Ricardo Lüders author
Replied on 22 Nov, 2017
Thank you, Chris. Always happy to help.
-
Bill Catlin
Found the plugin useful on 20 Nov, 2017
As a newcomer to OctoberCMS, this plugin saved me countless hours configuring and writing JWT into a new ecosystem. It particularly works great with Ricardo's Angular 2 theme tailored also for OctoberCMS.
Ricardo has also been super helpful making critical updates to the plugin as system-wide version upgrades push through. I would definitely recommend this plugin.
-
Ricardo Lüders author
Replied on 21 Nov, 2017
Hi Bill,
Thank you very much. I'm happy that the plugin was useful. I'm always working to make great plugins.
Anytime you need support, you can reach me by email.
Best regards.
-
1.4.4 |
Updates dependencies Jan 23, 2021 |
---|---|
1.4.3 |
(REALLY) Fixes the dependencies. Jan 22, 2021 |
1.4.2 |
Fixes dependencies that was causing issues related to Carbon Jan 22, 2021 |
1.4.1 |
Adding support to Laravel 6 Jan 03, 2021 |
1.4.0 |
Dependencies updated Dec 18, 2020 |
1.3.3 |
Added Czech Language support Oct 13, 2020 |
1.3.2 |
Fix typo on JsonValidationException Aug 15, 2019 |
1.3.1 |
Small hotfix to fix the Carbon 2 incompatibility Mar 13, 2019 |
1.3.0 |
The AuthController was removed and splited into Single Action Controllers Mar 03, 2019 |
1.2.5 |
Fix the validations issues Jan 27, 2019 |
1.2.4 |
!!! Refresh token changes from PATCH to POST and now requires an data form parameter. Please, check the documentation or the UPDATED Postman collection. Dec 28, 2018 |
1.2.3 |
Fix get user endpoint Oct 03, 2018 |
1.2.2 |
License changes to GPLv3 Aug 18, 2018 |
1.2.1 |
Dependencies hotfix Jun 10, 2018 |
1.2.0 |
Upgrading the plugin and adding new features Jun 05, 2018 |
1.1.6 |
Handeling with Blacklisted tokens May 02, 2018 |
1.1.5 |
Using the loginAttribute from RainLab.User May 02, 2018 |
1.1.4 |
Small fix for the refresh route May 02, 2018 |
1.1.3 |
Adding the token refresh route May 01, 2018 |
1.1.2 |
Some email URL fixes Nov 20, 2017 |
1.1.1 |
Ads JWTAuth Facade Nov 20, 2017 |
1.1.0 |
Settings support added Mar 07, 2017 |
1.0.1 |
First version of JWTAuth Feb 28, 2017 |
From v1.1.* to v1.2.0
Change your routes:
/api/auth/account_activation
is now/api/auth/account-activation
/api/auth/forgot_password
is now/api/auth/forgot-password
/api/auth/reset_password
is now/api/auth/reset-password
/api/auth/reset_token
is now/api/auth/reset-token