README

A Silverstripe CMS module for managing .well-known/ directory endpoints.

Comes with native providers forJSON Web Key Sets (JWKS) and security.txt files.

Custom providers can be implemented with by implementing the WellKnownProvider interface.

Requirements

PHP 8.1 or higher
Silverstripe CMS 5.0 or higher

Installation

Install via Composer:

composer require archipro/silverstripe-wellknown

Configuration

Basic Setup

By default, no providers are registered. You can register providers via the YML config with Injector.

# _config/wellknown.yml
SilverStripe\Core\Injector\Injector:
  Archipro\SilverstripeWellKnown\Controllers\WellKnownController:
    properties:
      providers:
        - '%$Archipro\SilverstripeWellKnown\Providers\SecurityProvider'
  
  Archipro\SilverstripeWellKnown\Providers\SecurityProvider:
    properties:
      contact: 'mailto:security@example.com'
      expires: '2025-12-31T23:59:59Z'

Cache Configuration

There's a pre-defined cache. But you can customise it with the Injector.

# _config/cache.yml
SilverStripe\Core\Injector\Injector:
  Psr\SimpleCache\CacheInterface.WellKnown:
    factory: SilverStripe\Core\Cache\CacheFactory
    constructor:
      namespace: 'WellKnown'
      defaultLifetime: 3600

Built-in Providers

JSON Web Key Set (JWKS) Provider

Serves JSON Web Key Sets at /.well-known/jwks.json:

SilverStripe\Core\Injector\Injector:
  Archipro\SilverstripeWellKnown\Providers\JsonWebKeySetProvider:
    properties:
      keys:
        - '%$YourCustomJsonWebKey'

Your "keys" must implement the JsonWebKey interface. Since this is likely to be very specific to your exact use case, no native implementation is provided.

Security Provider

Serves security.txt files at /.well-known/security.txt per RFC 9116:

SilverStripe\Core\Injector\Injector:
  Archipro\SilverstripeWellKnown\Providers\SecurityProvider:
    properties:
      contact: 'mailto:security@example.com'
      expires: '2025-12-31T23:59:59Z'
      encryption: 'https://example.com/pgp-key.txt'
      acknowledgments: 'https://example.com/hall-of-fame.html'
      preferredLanguages: 'en, fr'
      canonical: 'https://example.com/.well-known/security.txt'
      policy: 'https://example.com/security-policy.html'
      hiring: 'https://example.com/jobs.html'

OpenID Configuration Provider

Serves OpenID Connect Discovery metadata at /.well-known/openid-configuration:

This is a minimal implementation designed to allow third parties to validate JWTs by pointing them to your JWKS endpoint. It implements a subset of the OpenID Connect Discovery specification (OpenID Connect Discovery 1.0).

SilverStripe\Core\Injector\Injector:
  Archipro\SilverstripeWellKnown\Providers\OpenIdConfigurationProvider:
    constructor:
      issuer: 'https://api.archipro.co.nz'
      jwksUri: 'https://api.archipro.co.nz/.well-known/jwks.json'
      responseTypesSupported: ['token']
      subjectTypesSupported: ['public']
      idTokenSigningAlgValuesSupported: ['RS256']
  
  # Register the provider
  Archipro\SilverstripeWellKnown\Controllers\WellKnownController:
    properties:
      providers:
        - '%$Archipro\SilverstripeWellKnown\Providers\JsonWebKeySetProvider'
        - '%$Archipro\SilverstripeWellKnown\Providers\SecurityProvider'
        - '%$Archipro\SilverstripeWellKnown\Providers\OpenIdConfigurationProvider'

Supported Fields:

issuer - The authorization server's issuer identifier (typically your API base URL)
jwksUri - URL to your JWKS endpoint
responseTypesSupported - Array of OAuth 2.0 response types supported
subjectTypesSupported - Array of subject identifier types supported
idTokenSigningAlgValuesSupported - Array of JWS signing algorithms supported

All fields are optional and configured via constructor parameters through the Injector.

Creating Custom Providers

1. Implement the WellKnownProvider Interface

<?php

namespace YourApp\Providers;

use Archipro\SilverstripeWellKnown\Contracts\WellKnownProvider;

class CustomProvider implements WellKnownProvider
{
    public function getPath(): string
    {
        return 'custom.json';
    }

    public function getContentType(): string
    {
        return 'application/json';
    }

    public function getContent(): string
    {
        return json_encode(['message' => 'Hello World']);
    }
}

2. Register Your Provider

SilverStripe\Core\Injector\Injector:
  Archipro\SilverstripeWellKnown\Controllers\WellKnownController:
    properties:
      providers:
        - '%$Archipro\SilverstripeWellKnown\Providers\JsonWebKeySetProvider'
        - '%$Archipro\SilverstripeWellKnown\Providers\SecurityProvider'
        - '%$YourApp\Providers\CustomProvider'

License

This project is licensed under the BSD-3-Clause License - see the LICENSE file for details.

archipro / silverstripe-wellknown

Maintainers

Details