OAuth2 JWT Authentication

# Introduction

OAuth2 JWT authentication is an efficient implementation of the OAuth 2.0 authentication scheme. It allows clients to authenticate securely and reliably using JSON Web Tokens (JWT), ensuring security while improving system performance and scalability.

OpenResty Edge provides developers with convenient page rule actions, making the implementation of OAuth2 JWT authentication simple and intuitive.

# Configuration Parameters

This action includes the following key parameters:

1. Key:

   • Discovery: Enter a discovery URL, such as https://accounts.google.com/.well-known/openid-configuration. This method automatically retrieves the configuration information required for OAuth2, including authorization server addresses, token endpoints, and signature public keys. If you need to generate the content for a discovery URL, you can refer to the content in Google OAuth 2.0 Service Discovery URL and review the specifications OpenID Connect Discovery 1.0 incorporating errata set 2 and OAuth 2.0 Authorization Server Metadata.
   • Symmetric Key: Enter the secret key used for encrypting and verifying JWT signatures.
   • Public Key: Enter the public key used for verifying JWT signatures (the private key is used for generating signatures).

2. Accept Unsupported Algorithms: This should be kept off by default to reject tokens signed with unsupported algorithms. Enabling this option will prevent token signature verification, posing a security risk.

3. Token Signing Algorithm: Supports various algorithms, including HS256, HS512, RS256, RS512, ES256, ES512, and none. Please choose an appropriate algorithm based on security requirements.

# Discovery URL Specifications

When selecting “Discovery” as the Key type, the content of the discovery URL should follow the OpenID Connect Discovery 1.0 specification:

1. Must use HTTPS protocol.
2. The standard path is typically /.well-known/openid-configuration.
3. The returned JSON document should contain complete OAuth2 and OpenID Connect configuration information.
4. Key fields include issuer, authorization_endpoint, token_endpoint, jwks_uri, etc.

# Practical Application Example

The following example demonstrates how to configure and test OAuth2 JWT authentication:

In this example, we choose:

• Key type: Symmetric key, with the value openresty.
• Signing algorithm: HS256 (HMAC with SHA-256)

# Test Scenarios

1. Request without Authentication Information:

   $ curl http://test.com/anything -v
   ...
   < HTTP/1.1 403 Forbidden
   ...
   

   Result: 403 status code, indicating access is forbidden.

2. Request with Incorrect Authentication Information:

   $ curl http://test.com/anything -H 'Authorization: Bearer invalid-token' -v
   ...
   < HTTP/1.1 403 Forbidden
   ...
   

   Result: Also returns a 403 status code.

3. Request with Correct Authentication Information:

   $ curl http://test.com/anything -H 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJmb28iOiJiYXIifQ._FOTfoCTzKHWcBDYf1rfRkg-g6D_Mg8dnccLR_geCH0' -v
   ...
   < HTTP/1.1 404 Not Found
   ...
   

   Result: Returns 404, indicating successful authentication but the requested resource does not exist.

# JWT Token Generation Example

Here’s an example of generating a JWT token using Lua:

File name: jwt-example.lua

local jwt = require "resty.jwt"

-- set up the payload
local payload = {
    iss = "your_issuer",
    sub = "user_id",
    exp = ngx.time() + 3600,  -- expires in 1 hour
    iat = ngx.time(),
    -- other custom fields
}

-- sign with a symmetric key
local jwt_token = jwt:sign(
    "openresty",  -- Your secret key
    {
        header = {typ = "JWT", alg = "HS256"},
        payload = payload
    }
)

ngx.say(jwt_token)

Run command:

/usr/local/openresty-utils/bin/resty2 jwt-example.lua

This example uses the resty.jwt library to generate a JWT token, setting common claims such as iss (issuer), sub (subject), exp (expiration time), and iat (issued at time). You can add other custom fields according to specific requirements.

Note: The example uses the HS256 algorithm and a symmetric key. In production environments, ensure you use a sufficiently complex key and take appropriate measures to protect the key’s security.

OAuth2 JWT authentication implemented in this way ensures security while improving system efficiency, making it an excellent choice for identity verification in modern web applications.