Skip to content

Commit e4c66f9

Browse files
valendesignsvalendesigns
committed
Rework docs & ensure token is generated with key-pair only
1 parent bb69088 commit e4c66f9

File tree

8 files changed

+300
-102
lines changed

8 files changed

+300
-102
lines changed

‎README.md

Lines changed: 0 additions & 54 deletions
This file was deleted.

‎composer.json

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
{
22
"name": "wp-api/jwt-auth",
33
"type": "wordpress-plugin",
4-
"description": "Experimental JWT Authentication plugin.",
4+
"description": "Enable JSON Web Token authentication for the WordPress REST API.",
55
"homepage": "https://github.com/WP-API/jwt-auth",
66
"license": "GPLv2",
77
"prefer-stable" : true,

‎jwt-auth.php

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@
1818
* License URI: http://www.gnu.org/licenses/gpl-2.0.txt
1919
* GitHub Plugin URI: https://github.com/WP-API/jwt-auth
2020
* Requires PHP: 5.6.20
21-
* Requires WP: 4.4.0
21+
* Requires WP: 5.2
2222
*/
2323

2424
define( 'JWT_AUTH_PLUGIN_DIR', dirname( __FILE__ ) );

‎readme.md

Lines changed: 139 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,139 @@
1+
<!-- DO NOT EDIT THIS FILE; it is auto-generated from readme.txt -->
2+
# JWT Auth
3+
4+
Enable JSON Web Token authentication for the WordPress REST API.
5+
6+
**Contributors:** [valendesigns](https://profiles.wordpress.org/valendesigns)
7+
**Tags:** [jwt](https://wordpress.org/plugins/tags/jwt), [json-web-token](https://wordpress.org/plugins/tags/json-web-token), [auth](https://wordpress.org/plugins/tags/auth), [authentication](https://wordpress.org/plugins/tags/authentication), [rest](https://wordpress.org/plugins/tags/rest), [wp-rest](https://wordpress.org/plugins/tags/wp-rest), [api](https://wordpress.org/plugins/tags/api), [wp-api](https://wordpress.org/plugins/tags/wp-api), [json](https://wordpress.org/plugins/tags/json), [wp-json](https://wordpress.org/plugins/tags/wp-json)
8+
**Requires at least:** 5.2
9+
**Tested up to:** 5.2
10+
**Stable tag:** 0.1.0
11+
**License:** [GPLv2 or later](http://www.gnu.org/licenses/gpl-2.0.html)
12+
**Requires PHP:** 5.6.20
13+
14+
[![Build Status](https://travis-ci.org/WP-API/jwt-auth.svg?branch=develop)](https://travis-ci.org/WP-API/jwt-auth) [![Coverage Status](https://coveralls.io/repos/WP-API/jwt-auth/badge.svg?branch=develop)](https://coveralls.io/github/WP-API/jwt-auth)
15+
16+
## Description ##
17+
18+
This plugin makes it possible to use a JSON Web Token (JWT) to securely authenticate a valid user requesting access to
19+
your WordPress REST API resources.
20+
21+
JSON Web Tokens are an open, industry standard [RFC 7519](https://tools.ietf.org/html/rfc7519) method for representing
22+
claims securely between two parties.
23+
24+
## Installation ##
25+
26+
This plugin is not currently listed in the WordPress Plugin Directory. You'll need to install it manually.
27+
28+
1. [Download](https://github.com/WP-API/jwt-auth/archive/develop.zip) the latest version of the `jwt-auth` plugin.
29+
1. Go to Plugins > Add New.
30+
1. Click Upload Plugin to display the WordPress Plugin upload field.
31+
1. Click Choose File to navigate your local file directory.
32+
1. Select the WordPress Plugin zip archive you wish to upload and install.
33+
1. Click Install Now to install the WordPress Plugin.
34+
1. The resulting installation screen will list the installation as successful or note any problems during the install.
35+
1. If successful, click Activate Plugin to activate it, or Return to Plugin Installer for further actions.
36+
37+
## Generate Tokens ##
38+
39+
In order to generate an access and refresh token, you must be an authenticate user. There are a couple ways to
40+
authenticate a user, but only one works for tokens.
41+
42+
When generating a token we must authenticate with what is called an application password. This allows us to invalidate
43+
both the access token and refresh token by adding the API key to the tokens private claim. This ensures that when a
44+
token is used that has a valid API key it will authenticate the request, but if the key has been revoked the token
45+
becomes invalidated and cannot authenticate access to the request.
46+
47+
Application passwords protect us from the threat of long-lived tokens. Tokens are never stored on a server anywhere,
48+
and they work until they expire, which could be filtered to be a long time from now. So what we do is decoded the token
49+
and look for our safe and revocable application password inside the private claim. And since an application password
50+
cannot be used to login to WordPress, it only exists to generate tokens, we now have a secure separation of access and
51+
authentication.
52+
53+
If you try to generate a token with you username and password:
54+
55+
```bash
56+
curl -X POST https://example.org/wp-json/wp/v2/token \
57+
-F username=admin \
58+
-F password=password
59+
```
60+
61+
You should see an error like this:
62+
63+
```javascript
64+
{
65+
"code": "rest_authentication_required_api_key_secret",
66+
"message": "An API key-pair is required to generate a token.",
67+
"data": {
68+
"status": 403
69+
}
70+
}
71+
```
72+
73+
Now with an application password:
74+
75+
```bash
76+
curl -X POST https://example.org/wp-json/wp/v2/token \
77+
-F api_key=12345ascde \
78+
-F api_secret=54321edcba
79+
```
80+
81+
You should see something like this:
82+
83+
```javascript
84+
{
85+
"access_token": "YOUR_ACCESS_TOKEN",
86+
"data": {
87+
"user": {
88+
"id": 1,
89+
"type": "wp_user",
90+
"user_login": "admin",
91+
"user_email": "[email protected]",
92+
"api_key": "12345ascde"
93+
}
94+
},
95+
"exp": 604800,
96+
"refresh_token": "YOUR_REFRESH_TOKEN"
97+
}
98+
```
99+
100+
The `access_token` field is what you'll use for subsequent requests. For example, to fetch the user data, you could
101+
perform a request like:
102+
103+
```bash
104+
curl -X GET https://sample.org/wp-json/wp/v2/users/1 \
105+
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN'
106+
```
107+
108+
> Note that the header reads `Bearer YOUR_ACCESS_TOKEN`. Ensure you include the word "Bearer" (with a space after it)
109+
in order to be properly authenticated.
110+
111+
Now the `refresh_token` field is a special kind of token that can be used to obtain a renewed access token when it
112+
finally expires.
113+
114+
That request would be like this:
115+
116+
```bash
117+
curl -X POST https://example.org/wp-json/wp/v2/token \
118+
-F refresh_token=YOUR_REFRESH_TOKEN
119+
```
120+
121+
## Generate Application Passwords ##
122+
123+
In order to generate a token you first need to create an application password, or what we also refer to as a key-pair.
124+
To create a key-pair you have to first log into the WordPress administrative panel and go to your profile page. There
125+
you will see a section that gives you the ability to generate a named key-pair, download the key-pair, and generate
126+
and download new tokens, as well.
127+
128+
By ensuring only users that can login to WordPress can create a key-pair and only key-pairs can generate tokens we get
129+
all the benefits of implementing other security systems like 2factor authentication to secure users and don't have to
130+
worry about defending that side of the user authentication flow.
131+
132+
## Contributing ##
133+
134+
Contributors Welcome! The best way to get involved is to reach out via the [#core-restapi](https://wordpress.slack.com/messages/core-restapi/) channel in [Slack](https://make.wordpress.org/chat/). Meetings are held weekly [Thursdays @ 06:00 UTC](https://www.timeanddate.com/worldclock/timezone/utc).
135+
136+
## License ##
137+
138+
`jwt-auth` is licensed under [GNU General Public License v2](/LICENSE)
139+

‎readme.txt

Lines changed: 135 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,135 @@
1+
=== JWT Auth ===
2+
Contributors: valendesigns
3+
Tags: jwt, json-web-token, auth, authentication, rest, wp-rest, api, wp-api, json, wp-json
4+
Requires at least: 5.2
5+
Tested up to: 5.2
6+
Stable tag: 0.1.0
7+
License: GPLv2 or later
8+
License URI: http://www.gnu.org/licenses/gpl-2.0.html
9+
Requires PHP: 5.6.20
10+
11+
Enable JSON Web Token authentication for the WordPress REST API.
12+
13+
== Description ==
14+
15+
This plugin makes it possible to use a JSON Web Token (JWT) to securely authenticate a valid user requesting access to
16+
your WordPress REST API resources.
17+
18+
JSON Web Tokens are an open, industry standard [RFC 7519](https://tools.ietf.org/html/rfc7519) method for representing
19+
claims securely between two parties.
20+
21+
== Installation ==
22+
23+
This plugin is not currently listed in the WordPress Plugin Directory. You'll need to install it manually.
24+
25+
1. [Download](https://github.com/WP-API/jwt-auth/archive/develop.zip) the latest version of the `jwt-auth` plugin.
26+
1. Go to Plugins > Add New.
27+
1. Click Upload Plugin to display the WordPress Plugin upload field.
28+
1. Click Choose File to navigate your local file directory.
29+
1. Select the WordPress Plugin zip archive you wish to upload and install.
30+
1. Click Install Now to install the WordPress Plugin.
31+
1. The resulting installation screen will list the installation as successful or note any problems during the install.
32+
1. If successful, click Activate Plugin to activate it, or Return to Plugin Installer for further actions.
33+
34+
== Generate Tokens ==
35+
36+
In order to generate an access and refresh token, you must be an authenticate user. There are a couple ways to
37+
authenticate a user, but only one works for tokens.
38+
39+
When generating a token we must authenticate with what is called an application password. This allows us to invalidate
40+
both the access token and refresh token by adding the API key to the tokens private claim. This ensures that when a
41+
token is used that has a valid API key it will authenticate the request, but if the key has been revoked the token
42+
becomes invalidated and cannot authenticate access to the request.
43+
44+
Application passwords protect us from the threat of long-lived tokens. Tokens are never stored on a server anywhere,
45+
and they work until they expire, which could be filtered to be a long time from now. So what we do is decoded the token
46+
and look for our safe and revocable application password inside the private claim. And since an application password
47+
cannot be used to login to WordPress, it only exists to generate tokens, we now have a secure separation of access and
48+
authentication.
49+
50+
If you try to generate a token with you username and password:
51+
52+
```bash
53+
curl -X POST https://example.org/wp-json/wp/v2/token \
54+
-F username=admin \
55+
-F password=password
56+
```
57+
58+
You should see an error like this:
59+
60+
```javascript
61+
{
62+
"code": "rest_authentication_required_api_key_secret",
63+
"message": "An API key-pair is required to generate a token.",
64+
"data": {
65+
"status": 403
66+
}
67+
}
68+
```
69+
70+
Now with an application password:
71+
72+
```bash
73+
curl -X POST https://example.org/wp-json/wp/v2/token \
74+
-F api_key=12345ascde \
75+
-F api_secret=54321edcba
76+
```
77+
78+
You should see something like this:
79+
80+
```javascript
81+
{
82+
"access_token": "YOUR_ACCESS_TOKEN",
83+
"data": {
84+
"user": {
85+
"id": 1,
86+
"type": "wp_user",
87+
"user_login": "admin",
88+
"user_email": "[email protected]",
89+
"api_key": "12345ascde"
90+
}
91+
},
92+
"exp": 604800,
93+
"refresh_token": "YOUR_REFRESH_TOKEN"
94+
}
95+
```
96+
97+
The `access_token` field is what you'll use for subsequent requests. For example, to fetch the user data, you could
98+
perform a request like:
99+
100+
```bash
101+
curl -X GET https://sample.org/wp-json/wp/v2/users/1 \
102+
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN'
103+
```
104+
105+
> Note that the header reads `Bearer YOUR_ACCESS_TOKEN`. Ensure you include the word "Bearer" (with a space after it)
106+
in order to be properly authenticated.
107+
108+
Now the `refresh_token` field is a special kind of token that can be used to obtain a renewed access token when it
109+
finally expires.
110+
111+
That request would be like this:
112+
113+
```bash
114+
curl -X POST https://example.org/wp-json/wp/v2/token \
115+
-F refresh_token=YOUR_REFRESH_TOKEN
116+
```
117+
118+
== Generate Application Passwords ==
119+
120+
In order to generate a token you first need to create an application password, or what we also refer to as a key-pair.
121+
To create a key-pair you have to first log into the WordPress administrative panel and go to your profile page. There
122+
you will see a section that gives you the ability to generate a named key-pair, download the key-pair, and generate
123+
and download new tokens, as well.
124+
125+
By ensuring only users that can login to WordPress can create a key-pair and only key-pairs can generate tokens we get
126+
all the benefits of implementing other security systems like 2factor authentication to secure users and don't have to
127+
worry about defending that side of the user authentication flow.
128+
129+
== Contributing ==
130+
131+
Contributors Welcome! The best way to get involved is to reach out via the [#core-restapi](https://wordpress.slack.com/messages/core-restapi/) channel in [Slack](https://make.wordpress.org/chat/). Meetings are held weekly [Thursdays @ 06:00 UTC](https://www.timeanddate.com/worldclock/timezone/utc).
132+
133+
== License ==
134+
135+
`jwt-auth` is licensed under [GNU General Public License v2](/LICENSE)

0 commit comments

Comments
 (0)