Problem Statement

Currently, octo-sts validates OIDC tokens against individual trust policies stored in .github/chainguard/{name}.sts.yaml files. While this provides repository-level security, organizations lack a centralized mechanism to control which OIDC issuers are permitted to federate with their repositories at the organization level.

This creates potential security gaps where:

• Malicious or compromised OIDC providers could potentially be used if they satisfy individual trust policies
• Organizations cannot enforce issuer standards across all repositories
• No defense-in-depth for OIDC issuer validation
• Difficult to audit which issuers are trusted across the organization

Proposed Solution

Add support for organization-wide trusted token issuer validation as an additional security layer that validates OIDC issuers before individual trust policy evaluation.

Implementation Overview

1. Configuration Location: .github/chainguard/trusted-token-issuers.yaml in the organization's .github repository
2. Validation Flow: Organization issuer validation → Individual trust policy validation
3. Backward Compatibility: When disabled or missing, all issuers are accepted (current behavior)

Configuration Format

# Organization OIDC Trusted Token Issuers Configuration
description: "Organization OIDC trusted token issuers configuration"
enabled: true

# List of exact trusted issuer URLs
trusted_issuers:
  - "https://token.actions.githubusercontent.com"
  - "https://accounts.google.com"

# List of issuer regex patterns for flexible matching
issuer_patterns:
  # AWS EKS OIDC issuers
  - "https://oidc\\.eks\\.[a-z0-9-]+\\.amazonaws\\.com/id/[A-Z0-9]+"

Benefits

Security

• Defense-in-depth: Adds an additional validation layer before trust policy evaluation
• Organization-wide control: Centralized management of permitted OIDC issuers
• Prevents unauthorized issuers: Blocks federation attempts from unexpected or compromised OIDC providers

Operational

• Git-based audit trail: Configuration changes tracked through Git history and pull requests
• Flexible matching: Support for both exact matches and regex patterns
• Zero breaking changes: Fully backward compatible with existing deployments

Compliance

• Centralized governance: Helps organizations meet security compliance requirements
• Auditable: Clear trail of what issuers are trusted and when changes were made

Technical Implementation

Core Components

• OrgTrustedTokenIssuersValidator - Main validation logic with LRU caching
• OrgTrustedTokenIssuersConfig - Configuration structure with YAML parsing
• URL format validation for security (HTTPS enforcement, malformed URL detection)
• Comprehensive test suite (38+ test cases covering all scenarios)

Performance Features

• LRU Cache: 50 entries with 5-minute TTL to minimize GitHub API calls
• Graceful degradation: Continues to work if GitHub API is unavailable
• Efficient regex compilation: Patterns compiled once and cached

Security Features

• HTTPS enforcement: Only HTTPS issuers are accepted
• URL validation: Rejects malformed URLs and suspicious patterns
• Pattern safety: Invalid regex patterns cause configuration rejection

Backward Compatibility

✅ Zero breaking changes

• When enabled: false or configuration missing, all issuers are accepted
• Existing trust policies continue to work unchanged
• No changes to existing API or behavior

Implementation Status

• ✅ Core implementation complete (pkg/octosts/org_trusted_token_issuers.go)
• ✅ Comprehensive test suite (100% pass rate)
• ✅ Documentation updated (README.md)
• ✅ Example configuration provided
• ✅ Backward compatibility verified

Use Cases

GitHub Actions Only Organization

enabled: true
trusted_issuers:
  - "https://token.actions.githubusercontent.com"

Multi-Cloud Enterprise

enabled: true
trusted_issuers:
  - "https://token.actions.githubusercontent.com"
  - "https://accounts.google.com"
issuer_patterns:
  - "https://oidc\\.eks\\.[a-z0-9-]+\\.amazonaws\\.com/id/[A-Z0-9]+"
  - "https://login\\.microsoftonline\\.com/[a-f0-9-]+/v2\\.0"

Testing

The implementation includes comprehensive testing:

• URL format validation (valid/invalid/malformed issuers)
• Pattern compilation and matching
• Cache management (LRU eviction, TTL expiration)
• Configuration loading and error handling
• Real-world pattern matching (AWS EKS, Azure AD, GCP)

Migration Path

1. Deploy: Feature ships disabled by default
2. Configure: Organizations create configuration with enabled: false
3. Test: Validate configuration works in development
4. Enable: Set enabled: true and monitor
5. Refine: Adjust patterns based on usage

Alternatives Considered

1. Environment variables: Less flexible, harder to audit
2. Database storage: Adds infrastructure complexity
3. API-based configuration: Requires additional authentication mechanisms

Git-based configuration was chosen for auditability, pull request workflows, and consistency with existing trust policy management.

Questions for Maintainers

1. Are there any concerns with the proposed configuration file location?
2. Should we consider making the cache size/TTL configurable?
3. Any preferences for the configuration schema or field naming?

PR submitted: This feature is fully implemented with comprehensive tests and documentation. PR at #901.

Files involved:

• pkg/octosts/org_trusted_token_issuers.go (implementation)
• pkg/octosts/org_trusted_token_issuers_test.go (tests)
• README.md (documentation)