Skip to main content

JWT Authentication

JWT Authentication

Secure, stateless authentication for the Control Plane

JSON Web Tokens (JWT) are used throughout the Control Plane for authentication and authorization.

Token-based authentication

JWTs provide a secure, stateless mechanism for authenticating users and services across the distributed Control Plane architecture.

Overview​

JWT is an open standard (RFC 7519) for securely transmitting information between parties as a JSON object. The Control Plane uses JWTs for:

JWT Logo

👤 User Authentication

Authenticating end users accessing Control Plane services and interfaces.

🔄 Service-to-Service

Secure communication between Control Plane microservices.

🔒 Role-Based Access

Implementing fine-grained role-based access control across services.

🔑 API Authorization

Securing API endpoints against unauthorized access.

🔍 Identity Verification

Validating user and service identities throughout the system.

📊 Audit Trail

Tracking user actions through JWT subject and claims.

Why JWT?​

Stateless Architecture

JWTs enable a stateless authentication architecture:

  • No need to store session data on the server
  • Improved scalability with horizontally scaled services
  • Reduced database load for authentication checks
  • Self-contained tokens with all necessary information
  • Works seamlessly across multiple services

Security Features

JWTs provide robust security through:

  • Cryptographic signing to verify integrity
  • Expiration timestamps to limit token lifetime
  • Standard claim validation for issuer and audience
  • Support for multiple signing algorithms
  • Ability to encode permissions directly in the token

JWT Integration​

Middleware approach

The Control Plane uses middleware to handle JWT authentication, making it easy to secure endpoints with minimal code duplication.

The Control Plane uses the github.com/gofiber/contrib/jwt middleware for JWT authentication:

func setupAuth(app *fiber.App) {
    app.Use(jwt.New(jwt.Config{
        SigningKey:    []byte(os.Getenv("JWT_SECRET")),
        SigningMethod: "HS256",
        ErrorHandler: func(c *fiber.Ctx, err error) error {
            return c.Status(fiber.StatusUnauthorized).JSON(fiber.Map{
                "error": "Unauthorized",
                "message": err.Error(),
            })
        },
    }))
}

Protecting Routes​

Selective protection

Routes can be selectively protected by applying middleware at different levels or to specific route groups.

JWT Structure​

Token structure

Understanding the JWT structure is key to properly implementing and troubleshooting authentication in the Control Plane.

JWTs used in the Control Plane follow a standard three-part structure:

Example JWT​

{
  "header": {
    "alg": "RS256",
    "typ": "JWT",
    "kid": "2022-key-1"
  },
  "payload": {
    "sub": "user-123",
    "name": "John Doe",
    "roles": ["admin", "editor"],
    "groups": ["group-123", "group-456"],
    "exp": 1640995200,
    "iat": 1640908800,
    "iss": "https://auth.telekom.de"
  },
  "signature": "signature-data"
}

Standard Claims​

sub (Subject)

Unique identifier for the user or service. In the Control Plane, this is typically a user ID or service name.

exp (Expiration)

Unix timestamp indicating when the token expires. The Control Plane validates this claim to ensure tokens are not used after expiration.

iat (Issued At)

Unix timestamp indicating when the token was issued. Used for token tracking and audit purposes.

iss (Issuer)

Entity that issued the token. The Control Plane validates this to ensure tokens come from trusted sources.

aud (Audience)

Intended recipient of the token. Used to ensure tokens are used only with intended services.

jti (JWT ID)

Unique identifier for the token. Used for token revocation and tracking.

Custom Claims​

Custom claims

The Control Plane extends standard JWT claims with custom claims for role-based access control and multi-tenancy.

roles

Array of role strings assigned to the user.

Example:

{"roles": ["admin", "editor", "viewer"]}

Used for role-based access control across services.

groups

Array of group identifiers the user belongs to.

Example:

{"groups": ["finance", "marketing"]}

Used for organizational access boundaries.

permissions

Fine-grained permission descriptors.

Example:

{
"permissions": {
  "files": ["read", "write"],
  "users": ["read"]
}
}

tenant

Multi-tenancy identifier for resource isolation.

Example:

{"tenant": "org-123456"}

Ensures users can only access resources within their tenant.

RBAC with JWT​

Role-based access

Role-based access control is implemented through JWT claims, allowing for consistent access control across all Control Plane services.

Role Hierarchy​

Role hierarchy

The Control Plane implements a role hierarchy where higher-level roles inherit permissions from lower-level roles.

Token Validation​

Comprehensive validation

Always validate JWT tokens thoroughly for security. The Control Plane performs multiple validation steps to ensure token integrity and authenticity.

The Control Plane validates JWTs for:

✅ Signature Integrity

Verifies the token has not been tampered with using cryptographic signatures.

⏱️ Expiration Time

Checks that the token has not expired based on the 'exp' claim.

🔍 Issuer Validation

Confirms the token was issued by a trusted source using the 'iss' claim.

👥 Audience Verification

Ensures the token is intended for the current service using the 'aud' claim.

🔄 Not Before Time

Verifies the token is not used before its valid time using the 'nbf' claim.

⚙️ Algorithm Validation

Confirms the token uses the expected signing algorithm.

Token Generation​

Token issuance

Services in the Control Plane generate JWTs for clients after successful authentication, using secure methods to create signed tokens.

Services in the Control Plane generate JWTs for clients:

Security Best Practices​

JWT security

The Control Plane follows these security best practices for JWT implementation to minimize vulnerability risks.

Short-lived Tokens

The Control Plane uses short-lived access tokens to reduce the risk of token misuse:

  • Access tokens expire in 1 hour or less
  • Refresh tokens have a maximum lifetime of 7 days
  • Session tokens include device fingerprinting
  • Critical operations require re-authentication

Secret Management

JWT signing secrets are carefully managed:

  • Secrets stored in Kubernetes secrets or Vault
  • Different keys for development and production
  • Regular key rotation (every 90 days)
  • Key compromise procedures in place
  • Minimum 256-bit key strength

Algorithm Selection

The Control Plane uses robust algorithms:

  • RS256 (RSA Signature with SHA-256) for production
  • HS256 (HMAC with SHA-256) for development/testing
  • Explicitly verifies the algorithm in tokens
  • Rejects tokens with "none" algorithm

Transport Security

JWTs are always transmitted securely:

  • TLS/HTTPS for all API communications
  • Token transmitted in Authorization header
  • No storage in local storage or cookies (XSS protection)
  • Secure, HttpOnly cookies when browser storage is needed

Gofiber

Learn about the web framework used in conjunction with JWT authentication.

View Gofiber

Architecture

Understand how JWT fits into the overall Control Plane architecture.

View Architecture