PHPackages                             usefulteam/jwt-auth - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Authentication & Authorization](/categories/authentication)
4. /
5. usefulteam/jwt-auth

ActiveWordpress-plugin[Authentication & Authorization](/categories/authentication)

usefulteam/jwt-auth
===================

JWT Auth

3.0.2(2y ago)13521454[41 issues](https://github.com/usefulteam/jwt-auth/issues)[12 PRs](https://github.com/usefulteam/jwt-auth/pulls)GPLv3PHPCI passing

Since Aug 6Pushed 2mo ago9 watchersCompare

[ Source](https://github.com/usefulteam/jwt-auth)[ Packagist](https://packagist.org/packages/usefulteam/jwt-auth)[ RSS](/packages/usefulteam-jwt-auth/feed)WikiDiscussions master Synced 4d ago

READMEChangelog (2)Dependencies (4)Versions (8)Used By (0)

JWT Auth
========

[](#jwt-auth)

WordPress JWT (JSON Web Token) Authentication allows you to do REST API authentication via token. It's a simple, non-complex, and easy to use.

This plugin probably is the most convenient way to do JWT Authentication in WordPress. Download it from [WordPress plugin page](https://wordpress.org/plugins/jwt-auth/).

- Support & question: [WordPress support forum](https://wordpress.org/support/plugin/jwt-auth/)
- Reporting plugin's bug: [GitHub issues tracker](https://github.com/usefulteam/jwt-auth/issues)
- [Discord channel](https://discord.gg/DgECpEg) also available.

Requirements
------------

[](#requirements)

### PHP

[](#php)

Minimum PHP version: 7.2

### Enable PHP HTTP Authorization Header

[](#enable-php-http-authorization-header)

#### Shared Hosts

[](#shared-hosts)

Most shared hosts have disabled the **HTTP Authorization Header** by default.

To enable this option you'll need to edit your **.htaccess** file by adding the following:

```
RewriteEngine on
RewriteCond %{HTTP:Authorization} ^(.*)
RewriteRule ^(.*) - [E=HTTP_AUTHORIZATION:%1]

```

#### WPEngine

[](#wpengine)

To enable this option you'll need to edit your **.htaccess** file by adding the following (see [this issue](https://github.com/Tmeister/wp-api-jwt-auth/issues/1)):

```
SetEnvIf Authorization "(.*)" HTTP_AUTHORIZATION=$1

```

Installation
------------

[](#installation)

### Through the WordPress Administrative Area:

[](#through-the-wordpress-administrative-area)

- From WordPress administrative area, go to Plugins -> Add New
- Search for *JWT Auth*
- Install it
- Easily configure it (see [Configuration](#configuration) below)
- and then activate it

### Download Manually:

[](#download-manually)

- Download the plugin from [WordPress plugins page](https://wordpress.org/plugins/jwt-auth/)
- Upload to your wp-content directory
- Easily configure it (see [Configuration](#configuration) below)
- Activate it from *Plugins* menu in admin area

Configuration
-------------

[](#configuration)

### Configurate the Secret Key

[](#configurate-the-secret-key)

The JWT needs a **secret key** to sign the token. It must be unique and never be revealed.

To add the **secret key**, edit your wp-config.php file and add a new constant called **JWT\_AUTH\_SECRET\_KEY**.

```
define('JWT_AUTH_SECRET_KEY', 'your-top-secret-key');
```

You can use a string from here

### Configurate CORs Support

[](#configurate-cors-support)

This plugin has the option to enable [CORs](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing) support.

To enable the CORs Support edit your wp-config.php file and add a new constant called **JWT\_AUTH\_CORS\_ENABLE**

```
define('JWT_AUTH_CORS_ENABLE', true);
```

Finally activate the plugin within the plugin dashboard.

Namespace and Endpoints
-----------------------

[](#namespace-and-endpoints)

When the plugin is activated, a new namespace is added.

```
/jwt-auth/v1

```

Also, three new endpoints are added to this namespace.

EndpointHTTP Verb*/wp-json/jwt-auth/v1/token*POST*/wp-json/jwt-auth/v1/token/validate*POST*/wp-json/jwt-auth/v1/token/refresh*POSTRequesting/ Generating Token
----------------------------

[](#requesting-generating-token)

`/wp-json/jwt-auth/v1/token`

To generate token, submit a POST request to this endpoint. With `username` and `password` as the parameters.

It will validates the user credentials, and returns success response including a token if the authentication is correct or returns an error response if the authentication is failed.

You can use the optional parameter `device` with the device identifier to let user manage the device access in your profile. If this parameter is empty, it is ignored.

#### Sample of success response when trying to generate token:

[](#sample-of-success-response-when-trying-to-generate-token)

```
{
	"success": true,
	"statusCode": 200,
	"code": "jwt_auth_valid_credential",
	"message": "Credential is valid",
	"data": {
		"token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwczpcL1wvcG9pbnRzLmNvdXZlZS5jby5pZCIsImlhdCI6MTU4ODQ5OTE0OSwibmJmIjoxNTg4NDk5MTQ5LCJleHAiOjE1ODkxMDM5NDksImRhdGEiOnsidXNlciI6eyJpZCI6MX19fQ.w3pf5PslhviHohmiGF-JlPZV00XWE9c2MfvBK7Su9Fw",
		"id": 1,
		"email": "contactjavas@gmail.com",
		"nicename": "contactjavas",
		"firstName": "Bagus Javas",
		"lastName": "Heruyanto",
		"displayName": "contactjavas"
	}
}
```

#### Sample of error response when trying to generate token:

[](#sample-of-error-response-when-trying-to-generate-token)

```
{
	"success": false,
	"statusCode": 403,
	"code": "invalid_username",
	"message": "Unknown username. Try again or check your email address.",
	"data": []
}
```

Once you get the token, you must store it somewhere in your application. It can be:

- using **cookie**
- or using **localstorage**
- or using a wrapper like [localForage](https://localforage.github.io/localForage/) or [PouchDB](https://pouchdb.com/)
- or using local database like SQLite or [Hive](https://docs.hivedb.dev/#/)
- or your choice based on app you develop ;)

Then you should pass this token as *Bearer Authentication* header to every API call. The header format is:

`Authorization: Bearer your-generated-token`

and here's an example:

```
"Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwczpcL1wvcG9pbnRzLmNvdXZlZS5jby5pZCIsImlhdCI6MTU4ODQ5OTE0OSwibmJmIjoxNTg4NDk5MTQ5LCJleHAiOjE1ODkxMDM5NDksImRhdGEiOnsidXNlciI6eyJpZCI6MX19fQ.w3pf5PslhviHohmiGF-JlPZV00XWE9c2MfvBK7Su9Fw";

```

The **jwt-auth** will intercept every call to the server and will look for the authorization header, if the authorization header is present, it will try to decode the token and will set the user according with the data stored in it.

If the token is valid, the API call flow will continue as always.

Validating Token
----------------

[](#validating-token)

You likely **don't need** to validate the token your self. The plugin handle it for you like explained above.

But if you want to test or validate the token manually, then send a **POST** request to this endpoint (don't forget to set your *Bearer Authorization* header):

`/wp-json/jwt-auth/v1/token/validate`

#### Valid Token Response

[](#valid-token-response)

```
{
	"success": true,
	"statusCode": 200,
	"code": "jwt_auth_valid_token",
	"message": "Token is valid",
	"data": []
}

```

Refreshing the Access Token
---------------------------

[](#refreshing-the-access-token)

For security reasons, third-party applications that are integrating with your authentication server will not store the user's username and password. Instead they will store the refresh token in a user-specific storage that is only accessible for the user. The refresh token can be used to re-authenticate as the same user and generate a new access token.

When authenticating with `username` and `password` as the parameters to `/wp-json/jwt-auth/v1/token`, a refresh token is sent as a cookie in the response.

`/wp-json/jwt-auth/v1/token`

To generate new access token using the refresh token, submit a POST request to the token endpoint together with the `refresh_token` cookie.

Use the optional parameter `device` with the device identifier to associate the token with that device.

If the refresh token is valid, then you receive a new access token in the response.

By default, each access token expires after 10 minutes.

`/wp-json/jwt-auth/v1/token/refresh`

To generate new refresh token using the refresh token, submit a POST request to the token refresh endpoint together with the `refresh_token` cookie.

Use the optional parameter `device` with the device identifier to associate the refresh token with that device.

If the refresh token is valid, then you receive a new refresh token as a cookie in the response.

By default, each refresh token expires after 30 days.

### Refresh Token Rotation

[](#refresh-token-rotation)

Whenever you are authenticating afresh or refreshing the refresh token, only the last issued refresh token remains valid. All previously issued refresh tokens can no longer be used.

This means that a refresh token cannot be shared. To allow multiple devices to authenticate in parallel without losing access after another device re-authenticated, use the parameter `device` with the device identifier to associate the refresh token only with that device.

```
curl -F device="abc-def" -F username=myuser -F password=mypass /wp-json/jwt-auth/v1/token
```

```
curl -F device="abc-def" -b "refresh_token=123.abcdef..." /wp-json/jwt-auth/v1/token
```

```
curl -F device="abc-def" -b "refresh_token=123.abcdef..." /wp-json/jwt-auth/v1/token/refresh
```

Error Responses
---------------

[](#error-responses)

If the token is invalid an error will be returned. Here are some samples of errors:

**No Secret Key**

```
{
	"success": false,
	"statusCode": 500,
	"code": "jwt_auth_bad_config",
	"message": "JWT is not configured properly.",
	"data": []
}
```

**No HTTP\_AUTHORIZATION Header**

```
{
	"success": false,
	"statusCode": 401,
	"code": "jwt_auth_no_auth_header",
	"message": "Authorization header not found.",
	"data": []
}
```

**Bad Iss**

```
{
	"success": false,
	"statusCode": 401,
	"code": "jwt_auth_bad_iss",
	"message": "The iss do not match with this server.",
	"data": []
}
```

**Invalid Signature**

```
{
	"success": false,
	"statusCode": 401,
	"code": "jwt_auth_invalid_token",
	"message": "Signature verification failed",
	"data": []
}
```

**Incomplete Payload**

```
{
	"success": false,
	"statusCode": 401,
	"code": "jwt_auth_bad_request",
	"message": "User ID not found in the token.",
	"data": []
}
```

**User Not Found**

```
{
	"success": false,
	"statusCode": 401,
	"code": "jwt_auth_user_not_found",
	"message": "User doesn't exist",
	"data": []
}
```

**Expired Token**

```
{
	"success": false,
	"statusCode": 401,
	"code": "jwt_auth_invalid_token",
	"message": "Expired token",
	"data": []
}
```

**Obsolete Token**

```
{
	"success": false,
	"statusCode": 401,
	"code": "jwt_auth_obsolete_token",
	"message": "Token is obsolete",
	"data": []
}
```

**Invalid Refresh Token**

```
{
	"success": false,
	"statusCode": 401,
	"code": "jwt_auth_invalid_refresh_token",
	"message": "Invalid refresh token",
	"data": []
}
```

**Obsolete Refresh Token**

```
{
	"success": false,
	"statusCode": 401,
	"code": "jwt_auth_obsolete_refresh_token",
	"message": "Refresh token is obsolete",
	"data": []
}
```

**Expired Refresh Token**

```
{
	"success": false,
	"statusCode": 401,
	"code": "jwt_auth_expired_refresh_token",
	"message": "Refresh token has expired",
	"data": []
}
```

Available Filter Hooks
----------------------

[](#available-filter-hooks)

**JWT Auth** is developer friendly and has some filters available to override the default settings.

### jwt\_auth\_cors\_allow\_headers

[](#jwt_auth_cors_allow_headers)

The `jwt_auth_cors_allow_headers` allows you to modify the available headers when the CORs support is enabled.

Default Value:

```
'X-Requested-With, Content-Type, Accept, Origin, Authorization'

```

Usage example:

```
/**
 * Change the allowed CORS headers.
 *
 * @param string $headers The allowed headers.
 * @return string The allowed headers.
 */
add_filter(
	'jwt_auth_cors_allow_headers',
	function ( $headers ) {
		// Modify the headers here.
		return $headers;
	}
);
```

### jwt\_auth\_authorization\_header

[](#jwt_auth_authorization_header)

The **jwt\_auth\_authorization\_header** allows you to modify the Authorization header key used to validating a token. Useful when the server already uses the 'Authorization' key for another auth method.

Default value:

```
'HTTP_AUTHORIZATION'

```

Usage example:

```
/**
 * Modify the response of Authorization header key.
 *
 * @param string $header The Authorization header key.
 * .
 * @return string The Authorization header key.
 */
add_filter(
	'jwt_auth_authorization_header',
	function ( $header ) {
		// Modify the response here.
		return $header;
	},
	10,
	1
);
```

### jwt\_auth\_iss

[](#jwt_auth_iss)

The **jwt\_auth\_iss** allows you to change the [**iss**](https://tools.ietf.org/html/rfc7519#section-4.1.1) value before the payload is encoded to be a token.

Default Value:

```
get_bloginfo( 'url' )

```

Usage example:

```
/**
 * Change the token issuer.
 *
 * @param string $iss The token issuer.
 * @return string The token issuer.
 */
add_filter(
	'jwt_auth_iss',
	function ( $iss ) {
		// Modify the "iss" here.
		return $iss;
	}
);
```

### jwt\_auth\_not\_before

[](#jwt_auth_not_before)

The `jwt_auth_not_before` allows you to change the [**nbf**](https://tools.ietf.org/html/rfc7519#section-4.1.5) value before the payload is encoded to be a token

Default Value:

```
// Creation time.
time()

```

Usage example:

```
/**
 * Change the token's nbf value.
 *
 * @param int $not_before The default "nbf" value in timestamp.
 * @param int $issued_at The "iat" value in timestamp.
 *
 * @return int The "nbf" value.
 */
add_filter(
	'jwt_auth_not_before',
	function ( $not_before, $issued_at ) {
		// Modify the "not_before" here.
		return $not_before;
	},
	10,
	2
);
```

### jwt\_auth\_expire

[](#jwt_auth_expire)

The `jwt_auth_expire` allows you to change the [**exp**](https://tools.ietf.org/html/rfc7519#section-4.1.4) value before the payload is encoded to be a token

Default Value:

```
time() + (MINUTE_IN_SECONDS * 10)

```

Usage example:

```
/**
 * Change the token's expire value.
 *
 * @param int $expire The default "exp" value in timestamp.
 * @param int $issued_at The "iat" value in timestamp.
 *
 * @return int The "nbf" value.
 */
add_filter(
	'jwt_auth_expire',
	function ( $expire, $issued_at ) {
		// Modify the "expire" here.
		return $expire;
	},
	10,
	2
);
```

### jwt\_auth\_refresh\_expire

[](#jwt_auth_refresh_expire)

The `jwt_auth_refresh_expire` filter hook allows you to change the expiration date of the refresh token.

Default Value:

```
time() + (DAY_IN_SECONDS * 30)

```

Usage example:

```
/**
 * Change the refresh token's expiration time.
 *
 * @param int $expire The default expiration timestamp.
 * @param int $issued_at The current time.
 *
 * @return int The custom refresh token expiration timestamp.
 */
add_filter(
	'jwt_auth_refresh_expire',
	function ( $expire, $issued_at ) {
		// Modify the "expire" here.
		return $expire;
	},
	10,
	2
);
```

### jwt\_auth\_alg

[](#jwt_auth_alg)

The `jwt_auth_alg` allows you to change the supported signing [algorithm](https://tools.ietf.org/html/draft-ietf-jose-json-web-algorithms-40) for your application.

Default Value:

```
'HS256'

```

Usage example:

```
/**
 * Change the token's signing algorithm.
 *
 * @param string $alg The default supported signing algorithm.
 * @return string The supported signing algorithm.
 */
add_filter(
	'jwt_auth_alg',
	function ( $alg ) {
		// Change the signing algorithm here.
		return $alg;
	}
);
```

### jwt\_auth\_payload

[](#jwt_auth_payload)

The `jwt_auth_payload` allows you to modify all the payload / token data before being encoded and signed.

Default value:

```