| 1 |
=== JSON API Auth === |
| 2 |
|
| 3 |
Donate link: https://www.parorrey.com/donate/ |
| 4 |
Tags: json api, api, authenticate user, WordPress user authentication |
| 5 |
Contributors: parorrey |
| 6 |
Stable tag: 3.1.2 |
| 7 |
Requires at least: 3.0.1 |
| 8 |
Tested up to: 7.1 |
| 9 |
Requires PHP: 7.4 |
| 10 |
License: GPLv2 or later |
| 11 |
|
| 12 |
License URI: http://www.gnu.org/licenses/gpl-2.0.html |
| 13 |
|
| 14 |
Extends the JSON API Plugin for RESTful user authentication |
| 15 |
|
| 16 |
== Description == |
| 17 |
|
| 18 |
= Important: use RESTful JSON API for new integrations = |
| 19 |
|
| 20 |
JSON API Auth is retained for existing sites that still depend on the original JSON API plugin and its cookie-authentication workflow. For a new mobile app, headless site, external service, or AI-assisted integration, install <a href="https://wordpress.org/plugins/restful-json-api/">RESTful JSON API</a> instead. |
| 21 |
|
| 22 |
RESTful JSON API provides plugin-issued JWT bearer authentication, requires HTTPS by default for requests that handle passwords or tokens, and includes a broader set of endpoints organized into Core, Posts, User, Respond, and Widgets controllers. Its User controller includes signup, JWT login, token validation, profiles, avatars, password-reset requests, safe user meta, and authenticated comments, while the other controllers expose content, custom post type, taxonomy, media, menu, search, comment, and widget workflows. |
| 23 |
|
| 24 |
Existing JSON API Auth integrations can continue using this plugin. Because JWT bearer tokens replace the legacy cookie format and endpoint paths differ, test your client migration before deactivating the legacy JSON API stack. |
| 25 |
|
| 26 |
JSON API Auth extends the JSON API Plugin to allow RESTful user authentication. |
| 27 |
|
| 28 |
JSON API Plugin, that is required, was closed on August 7, 2019 from WordPress repository. You can download <a href="https://github.com/PI-Media/json-api">JSON API Plugin</a> from https://github.com/PI-Media/json-api until it is republished and available on WordPress. |
| 29 |
|
| 30 |
Features include: |
| 31 |
|
| 32 |
* Generate Auth Cookie for user authentication |
| 33 |
|
| 34 |
* Validate Auth Cookie |
| 35 |
|
| 36 |
* Get Current User Info |
| 37 |
|
| 38 |
For documentation: See 'Other Notes' tab above for usage examples. |
| 39 |
|
| 40 |
Credits: http://www.parorrey.com/solutions/json-api-auth/ |
| 41 |
|
| 42 |
== Installation == |
| 43 |
|
| 44 |
First you have to install the JSON API for WordPress Plugin (http://wordpress.org/extend/plugins/json-api/installation/). or You can download <a href="https://github.com/PI-Media/json-api">JSON API Plugin</a> from https://github.com/PI-Media/json-api |
| 45 |
|
| 46 |
To install JSON API Auth just follow these steps: |
| 47 |
|
| 48 |
* upload the folder "json-api-auth" to your WordPress plugin folder (/wp-content/plugins) |
| 49 |
|
| 50 |
* activate the plugin through the 'Plugins' menu in WordPress or by using the link provided by the plugin installer |
| 51 |
|
| 52 |
* activate the controller through the JSON API menu found in the WordPress admin center (Settings -> JSON API) |
| 53 |
|
| 54 |
== Screenshots == |
| 55 |
|
| 56 |
1. Call to generate_auth_cookie endpoint using Postman |
| 57 |
2. Call to get_currentuserinfo endpoint using Postman |
| 58 |
3. Call to validate_auth_cookie endpoint using Postman |
| 59 |
|
| 60 |
== Changelog == |
| 61 |
|
| 62 |
= 3.1.2 = |
| 63 |
* Tested and confirmed compatible with WordPress 7.1. |
| 64 |
* Confirmed the secure Parorrey donation link. |
| 65 |
|
| 66 |
= 3.1.1 = |
| 67 |
* Added a migration notice recommending the newer RESTful JSON API plugin for new projects. |
| 68 |
* Documented its JWT bearer authentication, HTTPS-by-default protection, and broader controller-based endpoint set. |
| 69 |
* Added secure WordPress.org and donation links. |
| 70 |
|
| 71 |
= 3.1.0 = |
| 72 |
* Tested and confirmed working with WordPress 7.0 |
| 73 |
* Bumped minimum PHP requirement to 7.4 |
| 74 |
* Replaced deprecated `wp_capabilities` user meta key with `$user->roles` for reliable role retrieval |
| 75 |
* Switched avatar retrieval to `get_avatar_url()` (WP 4.2+) with regex fallback, fixing broken avatar URLs in modern WordPress |
| 76 |
* Added `sanitize_text_field()` to POST parameter handling for improved input security |
| 77 |
* Fixed `isset()` check on `json_api->query->cookie` in cookie auth hook to avoid PHP notices |
| 78 |
|
| 79 |
= 3.0.0 = |
| 80 |
* Updated for WordPress version 6.8 |
| 81 |
|
| 82 |
= 2.9.1 = |
| 83 |
* Fixed a bug for generate_auth_cookie, get_currentuserinfo endpoints for avatar |
| 84 |
* Updated for WordPress version 6.4.1 |
| 85 |
|
| 86 |
= 2.9.0 = |
| 87 |
* Updated for WordPress version 6.1.1 |
| 88 |
|
| 89 |
= 2.8.0 = |
| 90 |
* Updated for WordPress version 6.0.1 |
| 91 |
|
| 92 |
= 2.7.1 = |
| 93 |
* Updated for WordPress version 5.9 |
| 94 |
|
| 95 |
= 2.7.0 = |
| 96 |
* Updated for wordpress version 5.8 |
| 97 |
|
| 98 |
= 2.6.0 = |
| 99 |
* Updated for wordpress version 5.7 |
| 100 |
|
| 101 |
= 2.5.0 = |
| 102 |
* Updated for wordpress version 5.5.3 |
| 103 |
|
| 104 |
= 2.4.0 = |
| 105 |
|
| 106 |
* Fixed bug in the generate_auth_cookie endpoint. |
| 107 |
|
| 108 |
= 2.3.0 = |
| 109 |
|
| 110 |
* Updated for JSON API Plugin diretory check error and updated action links. |
| 111 |
|
| 112 |
= 2.2.0 = |
| 113 |
|
| 114 |
* Updated for GitHub and settings action links. |
| 115 |
|
| 116 |
= 2.1.0 = |
| 117 |
|
| 118 |
* Updated for WordPress version & added JSON API plugin GitHub link due its closing down on WordPress repository. |
| 119 |
|
| 120 |
= 2.0.0 = |
| 121 |
|
| 122 |
* Updated for wordpress version |
| 123 |
|
| 124 |
|
| 125 |
== Frequently Asked Questions == |
| 126 |
|
| 127 |
Thanks to 'mattberg' who wrote the auth controller (https://github.com/mattberg/wp-json-api-auth) initially. I have added few methods and authored it as a WordPress plugin so that it could easily be searched and installed vis WordPress. |
| 128 |
|
| 129 |
* There are following methods available: validate_auth_cookie, generate_auth_cookie, clear_auth_cookie, get_currentuserinfo |
| 130 |
|
| 131 |
* nonce can be created by calling http://localhost/api/get_nonce/?controller=auth&method=generate_auth_cookie |
| 132 |
|
| 133 |
* You can then use 'nonce' value to generate cookie. http://localhost/api/auth/generate_auth_cookie/?nonce=f4320f4a67&username=Catherine&password=password-here |
| 134 |
|
| 135 |
* Use cookie like this with your other controller calls: http://localhost/api/contoller-name/method-name/?cookie=Catherine|1392018917|3ad7b9f1c5c2cccb569c8a82119ca4fd |
| 136 |
|
| 137 |
For instance, you have a new controller 'events' and want to allow users to post new 'event' using 'add_event' method. |
| 138 |
This is how you will call the end point with cookie and post the event with user info: |
| 139 |
|
| 140 |
http://localhost/api/events/add_event/?cookie=Catherine|1392018917|3ad7b9f1c5c2cccb569c8a82119ca4fd |
| 141 |
|
| 142 |
If you want sample code how it can be done, check 'JSON API User' plugin https://wordpress.org/plugins/json-api-user/. This Auth plugin is part of JSON API User plugin. |
| 143 |
|
| 144 |
= Method: validate_auth_cookie = |
| 145 |
|
| 146 |
It needs 'cookie' var. |
| 147 |
|
| 148 |
http://localhost/api/auth/validate_auth_cookie/?cookie=Catherine|1392018917|3ad7b9f1c5c2cccb569c8a82119ca4fd |
| 149 |
|
| 150 |
|
| 151 |
= Method: generate_auth_cookie = |
| 152 |
|
| 153 |
It needs `username`, `password` vars. `seconds` is optional. |
| 154 |
|
| 155 |
Then generate cookie: http://localhost/api/auth/generate_auth_cookie/?username=john&password=PASSWORD-HERE |
| 156 |
|
| 157 |
Optional 'seconds' var. It provided, generated cookie will be valid for that many seconds, otherwise default is for 14 days. |
| 158 |
|
| 159 |
generate cookie for 1 minute: http://localhost/api/auth/generate_auth_cookie/?username=john&password=PASSWORD-HERE&seconds=60 |
| 160 |
|
| 161 |
60 means 1 minute. |
| 162 |
|
| 163 |
|
| 164 |
= Method: get_currentuserinfo = |
| 165 |
|
| 166 |
It needs 'cookie' var. |
| 167 |
|
| 168 |
http://localhost/api/auth/get_currentuserinfo/?cookie=Catherine|1392018917|3ad7b9f1c5c2cccb569c8a82119ca4fd |
| 169 |
|
