envoy-xds-controller

Authentication and Authorization Implementation

This document provides an overview of the authentication and authorization implementation in the Envoy XDS Controller. For a comprehensive guide to all security features, see the Security Guide.

Table of Contents

  1. Components
  2. Authentication Flow
  3. Machine Authentication
  4. API Requests with Access Token
  5. ACL
  6. Libraries and Tools Used

Components

The authentication system consists of the following components:

  1. Dex (IdP): An identity provider supporting OpenID Connect (OIDC) and OAuth 2.0 protocols
  2. Web UI: A React Single Page Application using react-oidc-context for authentication flows
  3. Backend API Server: Handles token verification and authorization

Authentication Flow

The authentication flow follows the Authorization Code Grant with Proof Key for Code Exchange (PKCE) protocol, which is recommended for public clients such as SPAs:

  1. User Initiates Login
    • When a user attempts to access the application, the Web UI detects that the user is not authenticated
    • The Web UI initiates the authentication process using the react-oidc-context library
  2. Redirect to Dex (IdP)
    • The user is redirected to the Dex IdP login page
    • The authorization request includes a code challenge and code verifier as part of the PKCE extension for enhanced security
  3. User Authentication
    • The user enters their credentials (username and password) on the Dex login page
    • Dex authenticates the user
  4. Authorization Code Issuance
    • Upon successful authentication, Dex redirects the user back to the Web UI with an authorization code
  5. Token Exchange
    • The Web UI uses the authorization code and the code verifier to request tokens from Dex
    • Dex issues an ID Token and an Access Token to the Web UI
  6. User Logged In
    • The Web UI stores the tokens in Session storage in browser
    • The user’s authenticated state is updated in the application

Machine Authentication

In addition to the web-based authentication flow, Dex supports machine authentication, which allows systems to obtain tokens programmatically without going through the web flow. This is useful for:

Configuration

To enable machine authentication, add the following configuration to your Dex setup:

config:
  # ... other configuration ...
  enablePasswordDB: true
  oauth2:
    passwordConnector: local
  staticPasswords:
    - email: "sa@example.com"
      # bcrypt hash of the string "password": $(echo password | htpasswd -BinC 10 admin | cut -d: -f2)
      hash: "$2a$10$2b2cU8CPhOTaGrs1HRQuAueS7JTT5ZHsHSzYiFPm1leZck7Mc8T4W"
      username: "sa"
      userID: "08a8684b-db88-4b73-90a9-3cd1661f5466"

This configuration:

Obtaining Tokens

Once configured, you can obtain tokens using the Resource Owner Password Credentials grant type:

curl -L -X POST 'http://localhost:5556/token' \
-u 'envoy-xds-controller:' \
-H 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=password' \
--data-urlencode 'scope=openid' \
--data-urlencode 'username=sa@example.com' \
--data-urlencode 'password=password'

The response will contain the access token and ID token:

{
  "access_token": "eyJhbGc....",
  "token_type": "bearer",
  "expires_in": 86399,
  "id_token": "eyJhbGciOiJSUzI1N..."
}

These tokens can be used in the same way as tokens obtained through the web flow, as described in the API Requests with Access Token section.

Security Considerations

When using machine authentication:

For more information, see:

API Requests with Access Token

When the Web UI needs to make API requests to the backend server:

  1. Include Access Token

    • The Web UI includes the Access Token in the Authorization header of HTTP requests to the backend API server, using the Bearer scheme:

      Authorization: Bearer <access_token>
  2. Backend Token Verification
    • The backend API server intercepts incoming requests using middleware
    • The middleware extracts the Access Token from the Authorization header
  3. Token Validation
    • The middleware verifies the Access Token by:
      • Checking the token’s signature using the public keys from Dex (e.g., via JSON Web Keys (JWKs) endpoint)
      • Validating the token’s claims, such as issuer (iss), audience (aud), expiration time (exp), etc.
      • Ensuring the token has the necessary scopes and permissions
  4. Authorized Access
    • If the token is valid, the middleware allows the request to proceed to the appropriate handler
    • If the token is invalid or expired, the middleware responds with an appropriate HTTP error (e.g., 401 Unauthorized)

ACL

In addition to authentication and authorization, the system implements fine-grained access control to entities called nodes. The access control is configured via a configuration map (configmap), which defines the permissions for different user groups.

Configuration

The access control settings are defined in a JSON configuration, which is supplied to the backend API server through environment variables. An example configuration is as follows:

{
  "admins": ["*"],
  "authors": ["node1"],
  "users": ["node1", "node2"]
}

Access Control Mechanism

  1. User Groups from JWT Claims
    • When the API server receives a request with a JWT Access Token, it extracts the user’s group memberships from the token’s claims
    • The claims should include a list of groups (e.g., “groups”) the user belongs to
  2. Group-to-Node Mapping
    • The API server maps the user’s groups to the nodes they have access to, based on the configuration
    • For example:
      • Users in the “admins” group have access to all nodes (“*”)
      • Users in the “authors” group have access to “node1”
      • Users in the “users” group have access to “node1” and “node2”
  3. Data Filtering
    • When the user requests data, the API server filters the records and returns only those associated with the nodes the user has access to
    • This ensures that users can only access data relevant to their permissions

Example Scenario

User A:

User B:

User C:

Implementation Details

JWT Claims:

Configuration Loading:

Access Enforcement:

Default Access:

Libraries and Tools Used