planetadeleste/oc-jwtauth-plugin

JSON Web Token Authentication plugin for OctoberCMS with Lovata.Buddies

1.3.5 2021-05-07 11:42 UTC

Requires

• php: >=7.2
• tymon/jwt-auth: dev-develop

GPL-3.0-or-later

• Ricardo Lüders

• api
• Authentication
• cms
• jwt
• JSON Web Token
• october
• octobercms

README

Introduction

This plugin is a fork of rluders/oc-jwtauth-plugin, adapted to be used with Lovata.Buddies plugin instead of RainLab.Users

This plugin provides a JSON Web Tokens authentication mechanism for OctoberCMS integrated with Lovata.Buddies. It's essential for your web application built with Angular, Vue.js, React or other modern Javascript frameworks.

Requirements

• Lovata.Buddies plugin
• RLuders.CORS plugin (optional, but recommended)

Theme

• Angular Skeleton

Tutorials

• Creating Vue, Vuex and OctoberCMS APP - Login and Register by Watch and Learn

Installation

Yes, you can install it from the repository (but I'll not provide a documentation for that - in this case I'll assume that you know what you are doing). I strongly recommend that you install it from product page inside the OctoberCMS Marketplace.

Configuration

You must set a secret token for your application. Do do it, on October's Backend access: 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 account email or username. You can select it on RainLab.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
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 RainLab.User configuration.

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
email	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
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

[]

ERROR

Code: 422

{
  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

{
  token: (string)
}

ERROR

Code: 403

{
  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

{
  user: (object)
}

ERROR

Code: 404

{
  error: (user_not_found)
}

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