Download the PHP package phithi92/json-web-token without Composer

Json-Web-Token

The JsonWebToken PHP library enables seamless creation, signing, and validation of JSON Web Tokens (JWT) with support for JSON Web Signature (JWS) and JSON Web Encryption (JWE). Designed with a focus on security, it utilizes various cryptographic algorithms to ensure data integrity and confidentiality.

Table of Contents

• Overview
• Security Considerations
• Prerequisites
• Installation
• Usage Guide
  • Generate a Token
  • Validate a Token
  • Verify Structure and encryption
  • Verify Payload
  • Refresh a Token
  • Error Handling
• Supported Algorithms
• Running Tests and Benchmarks
  • PHPUnit Tests
  • PHPBench Tests
• Benchmark
• Support

Overview

This library adheres to the standards in RFC 7519 (JWT), RFC 7515 (JWS), and RFC 7516 (JWE). It uses HMAC algorithms like HS256 for token signing (JWS) and AES-based methods for token encryption (JWE), ensuring both data integrity and confidentiality.

Security Considerations

When working with JWTs, consider the following best practices:

• Store keys securely: Ensure private keys are stored securely and are not hardcoded in your application code.
• Use HTTPS: Always transmit tokens over HTTPS to prevent interception.
• Set expiration times: Limit token lifespans by setting expiration times to reduce risk in case of token compromise.

Prerequisites

Before using this library, ensure your environment meets the following requirements:

• PHP Version: 8.2 or higher
• PHP Extensions: openssl
• Composer: For managing dependencies

Installation

To integrate this library into your project, clone the repository or download the necessary files. It is recommended to use Composer for managing dependencies.

Step 1: Clone the Repository

Clone the project to your local environment:

Or, install the library directly via Composer:

Step 2: Install Dependencies

Ensure Composer is installed, and then run:

The project uses the following dependencies (defined in composer.json):

PHPUnit: Used for unit testing to ensure robustness. PHPBench: Used for benchmark to ensure efficiency.

Usage Guide

Generate a Token

To create a JWT, set up the signing algorithm and payload, then generate the token.

Refresh a Token

Refresh an existing JWT by extending its expiration.

Validate a Token

Verify Structure and encryption

To validate and decrypt a JWT, configure the algorithm manager and retrieve the payload.
Note: This validation covers only time-based claims (such as exp, nbf, and iat).
Validation of audience and issuer claims can be performed manually if required.

Once the token has been decrypted, further validations can be performed directly on the JwtPayload as needed. This allows for flexible, custom checks beyond the standard validation methods provided.

Verify Payload

Validation of audience and issuer claims can be performed manually if you need.

Validate Issuer

Validate Audience

The $audience parameter can be either a single value or an array. The validateAudience($audience) method checks whether the audience value specified in the token matches the given $audience. If $audience is an array, the validation will pass if any one value in the array matches the audience value in the token.

Example:

Suppose the token’s payload contains the audience value "example.com", and we pass the following array to validateAudience:

Error Handling

Handle exceptions for robust error management in your application:

Supported Algorithms

The JsonWebToken class supports a variety of cryptographic algorithms for both JSON Web Signature (JWS) and JSON Web Encryption (JWE). Below are the lists of supported algorithms:

JSON Web Signature (JWS) Algorithmen:

HS256, HS384, HS512, RS256, RS384, RS512, ES256, ES384, ES512, PS256, PS384, PS512

JSON Web Encryption (JWE) Algorithmen:

RSA-OAEP, RSA-OAEP+A192GCM, RSA-OAEP+A256GCM, RSA1_5, A128GCM, A192GCM, A256GCM

Running Tests and Benchmarks

This project includes both unit tests and benchmarks to ensure reliability and performance.

PHPUnit Tests

Unit tests are included to verify the functionality of the library. These tests cover token creation, validation, and error handling. To run the unit tests, use the following command:

All PHPUnit test cases are located in the tests/phpunit directory and ensure that the library functions correctly across various scenarios.

PHPBench Tests

Benchmarks are included to measure the performance of different algorithms and operations within the library. To run the benchmarks, use the following command:

Benchmarking

This project uses automated benchmarks that run with each new commit or pull request via GitHub Actions. You can view the benchmark results in the GitHub Actions Workflow.

How to Find the Results

1. Go to the Actions tab in this repository.
2. Select the latest Benchmark Workflow run.
3. Here, you’ll find detailed results for the current benchmarks.

Note: Benchmarks are updated automatically, so the latest results are always available in the most recent workflow run.

Support

Donations are a great way to support creators and their work. Every contribution helps sustain projects and shows appreciation for their efforts, making a real difference.