flipboxfactory/craft-jwt

There is no license information available for the latest version (1.1.0) of this package.

JWT Authorization

Installs: 9 040

Dependents: 0

Suggesters: 0

Security: 0

Stars: 11

Watchers: 4

Forks: 2

Open Issues: 1

Type:craft-plugin

1.1.0 2022-02-14 19:34 UTC

README

Join the chat at https://gitter.im/flipboxfactory/craft-jwt Latest Version Software License Build Status Coverage Status Quality Score Total Downloads

JWT (JSON Web Token) for Craft CMS assists in issuing and claiming tokens. The intent is to issue a token which, at a later time, can be claimed and used to perform various actions.
The life of a JWT is defined upon creation and

Use Cases

  • Protected downloads
  • Protected pages/content
  • Authorization to API
  • Tracking actions (by user)
  • Sharing downloads/pages to guests

To learn more about JWT visit JWT.IO

Requirements

This plugin requires Craft CMS 3.0 or later.

Installation

Simply run the following command from your project root:

composer require flipboxfactory/craft-jwt

Once the plugin is included in your project, navigate to the Control Panel, go to Settings → Plugins and click the “Install” button for the JWT Plugin.

Templating

The craft.jwt template variable provides access to the entire JWT plugin. To access the services, you may use:

Identity Service:

{% set token = craft.jwt.identity.issue(currentUser) %} {# To generate a token (store the identity) #}
{% set claim = craft.jwt.identity.claim(token|trim) %} {# To claim a token (retrieve the identity) #}

Route Service:

{% set token = craft.jwt.route.issue('action/path') %} {# To generate a token (store the action path) #}
{% set claim = craft.jwt.route.claim(token|trim) %} {# To claim a token (retrieve the action path) #}

Examples

Common usages of this plugin are as follows:

Self-Consumable API (Hybrid API - calling your own API)

Making calls to your own API is a great candidate for JWT Identity tokens. The flow works something like this:

  1. Set a JavaScript variable: let jwt = '{{ craft.jwt.identity.issue(currentUser) }}'
  2. Using Axois (or other HTTP client library), make a call to your own API using the JWT token created in step 1.
  3. Apply the Authentication filter to your API controller(s).
/**
 * @inheritdoc
 */
public function behaviors()
{
    return \craft\helpers\ArrayHelper::merge(
        parent::behaviors(),
        [
            'authenticator' => [
                'authMethods' => [
                    \flipbox\craft\jwt\filters\JwtHttpBearerAuth::class
                ]
            ]
        ]
    );
}

A full example of the Authentication filter implementation can be found in our RESTful API for Craft CMS

Protected Downloads (or page access)

Perhaps a user needs to access a protected page or file download. To circumvent exposing the url publicly, issue a JWT Route token.

Render template:
{% set token  = craft.jwt.route.issue(['templates/render', {'template': '_protected/template'}], currentUser)
{# the link will automatically render the template #}
<a href="{{ actionUrl("jwt/route", {jwt: token|trim}) }}">View Protected Page</a>
File Download
{% set asset = craft.assets.one() %}
{% set token  = craft.jwt.route.issue(['assets/thumb', {'uid': asset.uid, width: 100, height: 100}], currentUser) %}
<a href="{{ actionUrl("jwt/route", {jwt: token|trim}) }}">Download Protected File</a>

Note: It's important to note that in the File Download example, we're also passing the currentUser param when generating the token. As a result, when the action is processed we're assuming the identity of the user who issued the token prior to performing the action. This means a user doesn't have to be logged in to Craft.

Caution

JWTs created by this plugin are technically JWS (JSON Web Signature) tokens. The contents of a token can be easily decoded and viewed using tools such as jwt.io. It is important NOT to store sensitive data in a token. The Craft 'security key' is used to sign each token; ensuring the contents have not been tampered with.

A token is valid for

Contributing

Please see CONTRIBUTING for details.

Credits

License

The MIT License (MIT). Please see License File for more information.