JWT Robot Framework Library

A comprehensive Robot Framework library for JSON Web Token (JWT) operations, enabling robust testing of JWT-based authentication and authorization in your test automation.

🚀 Features

• Complete JWT Lifecycle: Generate, decode, validate, and analyze JWT tokens
• Multiple Algorithms: Support for HMAC, RSA, ECDSA, and PSS algorithms
• Advanced Validation: Comprehensive claim validation, expiration checking, and signature verification
• Security-First: Built-in protection against common JWT vulnerabilities
• Easy Integration: Simple keyword interface designed for Robot Framework
• Extensive Documentation: Complete keyword reference with examples
• Error Handling: Graceful error handling with detailed error messages
• Performance Optimized: Efficient token operations for test automation

📦 Installation

Using pip

pip install robotframework-jwtlibrary

From source

git clone https://github.com/ohmrefresh/robotframework-jwtlibrary.git
cd jwt-robotframework-library
pip install -e .

Dependencies

• Python 3.7+
• Robot Framework 4.0+
• PyJWT 2.0+

🏃 Quick Start

Basic Usage

*** Settings ***
Library    JWTLibrary

*** Variables ***
${SECRET_KEY}    your-secret-key-here

*** Test Cases ***
Basic JWT Operations
    # Create payload
    ${payload}=    Create Dictionary    user_id=123    role=admin
    
    # Generate token
    ${token}=    Generate JWT Token    ${payload}    ${SECRET_KEY}
    
    # Decode and verify
    ${decoded}=    Decode JWT Payload    ${token}    ${SECRET_KEY}
    Should Be Equal    ${decoded['user_id']}    123
    
    # Validate token
    ${is_valid}=    Verify JWT Token    ${token}    ${SECRET_KEY}
    Should Be True    ${is_valid}

Advanced Example

Advanced JWT Validation
    # Create comprehensive payload
    ${payload}=    Create Dictionary
    ...    iss=auth-service
    ...    sub=user-12345
    ...    aud=api-service
    ...    user_id=12345
    ...    role=admin
    ...    permissions=["read", "write", "delete"]
    
    # Generate token with custom expiration
    ${token}=    Generate JWT Token    ${payload}    ${SECRET_KEY}    expiration_hours=2
    
    # Comprehensive validation
    ${exp_info}=    Check JWT Expiration    ${token}
    Should Be Equal    ${exp_info['is_expired']}    ${False}
    
    ${claims_valid}=    Validate JWT Claims    ${token}    
    ...    {"role": "admin", "user_id": 12345}    ${SECRET_KEY}    ${True}
    Should Be True    ${claims_valid}
    
    ${aud_valid}=    Validate JWT Audience    ${token}    api-service
    Should Be True    ${aud_valid}

📚 Available Keywords

Token Generation

• Generate JWT Token - Creates JWT tokens with custom payloads
• Generate JWT Token With Claims - Creates tokens using keyword arguments
• Generate JWT Token Without Expiration - Creates non-expiring tokens
• Generate JWT Token With Custom Expiration - Creates tokens with specific expiration

Token Decoding

• Decode JWT Payload - Decodes token payloads with optional verification
• Decode JWT Header - Decodes token headers
• Get JWT Claim - Extracts specific claims from tokens
• Get Multiple JWT Claims - Extracts multiple claims
• Extract All JWT Claims - Gets all claims with metadata

Token Validation

• Verify JWT Token - Validates token signatures and expiration
• Check JWT Expiration - Checks token expiration status
• Validate JWT Claims - Validates expected claim values
• Check JWT Algorithm - Validates token algorithm
• Validate JWT Structure - Validates token format
• Check JWT Not Before - Validates nbf claim
• Validate JWT Audience - Validates audience claim

Utilities

• Create JWT Payload - Helper to create payload dictionaries
• Get JWT Token Info - Gets comprehensive token information
• Compare JWT Tokens - Compares two tokens
• Extract JWT Timestamps - Extracts timestamp claims
• Generate Current Timestamp - Creates current timestamp
• Generate Future Timestamp - Creates future timestamp
• Convert Timestamp To Datetime - Converts timestamps to datetime

🔧 Supported Algorithms

🎯 Use Cases

API Testing

Test API Authentication
    ${token}=    Generate JWT Token    {"user_id": 123}    ${API_SECRET}
    
    # Use token in API requests
    ${headers}=    Create Dictionary    Authorization=Bearer ${token}
    ${response}=    GET    ${API_URL}/protected    headers=${headers}
    Should Be Equal As Integers    ${response.status_code}    200

Microservices Testing

Test Service-to-Service Communication
    ${service_payload}=    Create Dictionary
    ...    iss=service-a
    ...    aud=service-b
    ...    scope=read:data
    
    ${service_token}=    Generate JWT Token    ${service_payload}    ${SERVICE_SECRET}
    
    # Validate token at receiving service
    ${claims_valid}=    Validate JWT Claims    ${service_token}
    ...    {"iss": "service-a", "aud": "service-b"}
    Should Be True    ${claims_valid}

Security Testing

Test Token Security
    ${token}=    Generate JWT Token    {"user_id": 123}    ${SECRET_KEY}
    
    # Test with tampered token
    ${tampered_token}=    Replace String    ${token}    .    X    count=1
    ${is_valid}=    Verify JWT Token    ${tampered_token}    ${SECRET_KEY}
    Should Be Equal    ${is_valid}    ${False}
    
    # Test token expiration
    ${expired_token}=    Generate JWT Token    {"user_id": 123}    ${SECRET_KEY}    
    ...    expiration_hours=0.001
    Sleep    1s
    ${exp_info}=    Check JWT Expiration    ${expired_token}
    Should Be True    ${exp_info['is_expired']}

🛡️ Security Considerations

• Secret Management: Never hardcode secrets in test files
• Algorithm Validation: Always verify the algorithm matches expectations
• Expiration Checking: Validate token expiration in security tests
• Claim Validation: Verify all security-relevant claims
• Signature Verification: Always verify signatures in production scenarios

📖 Documentation

• Installation Guide
• User Guide
• API Reference
• Examples
• Contributing Guidelines

🔍 Examples

Check out the examples directory for comprehensive usage examples:

• Basic Usage
• Advanced Features
• Real-world Scenarios

🧪 Testing

Run the test suite:

# Install development dependencies
pip install -r requirements-dev.txt

# Run unit tests
pytest tests/unit/

# Run Robot Framework tests
robot tests/robot/acceptance/

# Run all tests
make test