DOCSEARCHbyAlgolia
Submit Docs

caddy-security

repository·main·Indexed 25 days ago

https://github.com/greenpau/caddy-security

A security extension for the Caddy v2 web server providing authentication, authorization, and credential management. It includes an Authentication Plugin supporting Form-Based, Basic, Local, LDAP, OpenID Connect, OAuth 2.0, and SAML; an Authorization Plugin for validating JWT and PASETO tokens; and a Credentials Plugin for managing integrations. It also provides a SecretsManager interface for custom secret storage like HashiCorp Vault or AWS Secrets Manager.

Tokens
11.1K
Snippets
8
Records
55
Agent score
80%

What's inside caddy-security

  1. Overview of caddy-security features

    main

    caddy-security is a security application for Caddy v2 that provides a suite of plugins for managing identity and access control. It is divided into three primary functional areas:

    1. Authentication Plugin: Supports multiple authentication methods including Form-Based, Basic, Local, LDAP, OpenID Connect, OAuth 2.0, and SAML.
    2. Authorization Plugin: Handles HTTP request authorization by validating JWT (JSON Web Tokens) or PASETO tokens.
    3. Credentials Plugin: Provides mechanisms for managing credentials across various integrations.

  2. Corporate Contributor License Agreement (CCLA) requirements

    main

    Entities (Corporations) wishing to submit contributions to the caddy-security project must have a signed Corporate Contributor License Agreement (CCLA) on file with the Project Owner (Paul Greenberg). This agreement clarifies the intellectual property licenses granted by the entity to the Project Owner and its users.

    Key Terms for Corporations

    • Scope: The agreement allows an entity to submit contributions, authorize designated employees to submit on its behalf, and grant necessary copyright and patent licenses.
    • Ownership: The Corporation reserves all right, title, and interest in its Contributions, except for the specific licenses granted to the Project Owner and software recipients.
    • Copyright License: The Corporation grants a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare derivative works, publicly display, publicly perform, sublicense, and distribute the Contributions.
    • Patent License: The Corporation grants a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable patent license to make, use, sell, and import the Work, covering patent claims necessarily infringed by the Contribution(s).
    • Third-Party Work: If submitting work that is not the Corporation's original creation, it must be submitted separately, with full source details and license restrictions identified, and marked as Submitted on behalf of a third-party: [named here].
    • Employee Authorization: The Corporation is responsible for notifying the Project Owner of any changes to the list of designated employees authorized to submit contributions or changes to the Corporation's Point of Contact.

  3. Use the secrets: syntax for secret resolution

    main

    The configuration resolution logic supports a special syntax for retrieving values from a SecretsManager. To use a secret, provide a string in the following format:

    secrets:<manager_id>:<secret_key>

    • secrets: The required prefix.
    • <manager_id>: The unique identifier of the configured SecretsManager.
    • <secret_key>: The key used to look up the secret within that manager.

    Example: secrets:my-vault:api-key will attempt to find a manager with ID my-vault and retrieve the secret associated with api-key.

  4. How secret substitution works

    main

    Secret substitution is a two-step process performed during configuration resolution:

    1. Caddy Replacer Substitution: The system first uses the Caddy Replacer to resolve standard environment variables or other Caddy-native placeholders (e.g., {env.VAR_NAME}).
    2. Secret Manager Lookup: If the resulting string matches the secrets:<manager_id>:<secret_key> pattern, the system identifies the appropriate SecretsManager by its id and calls GetSecretByKey to fetch the actual sensitive value.

    This allows you to combine standard Caddy environment variable substitution with secure secret management in a single configuration field.

  5. Configure authorization policies in Caddyfile

    main

    You can define authorization policies within a Caddyfile using the security.authorization policy <name> directive. This allows you to create named policies that govern access control via ACLs, crypto requirements, bypass rules, and header injections.

    Each policy is defined within a block and can contain several sub-directives to configure its behavior.

    security.authorization policy <name> {
    crypto
    acl
    <allow|deny>
    bypass
    enable
    disable
    validate
    set
    with
    inject
}

  6. Configure Authorization ACLs in Caddyfile

    main

    Authorization Access Control Lists (ACLs) can be configured within the Caddyfile using the rule or default sub-directives. These rules define how access is granted or denied based on specific conditions.

    Using the rule directive

    The rule directive allows for granular control by defining a comment, an action (allow or deny), and specific conditions. Each rule is defined within a block.

    • comment: An optional description for the rule.
    • allow / deny: Sets the action for the rule.
    • Conditions: Any other key provided within the block is treated as a condition. Multiple conditions can be added to the rule.

    Using the default directive

    The default directive sets a fallback rule for the entire policy. It requires exactly one action.

    • Syntax: default <allow|deny>
    • Behavior: It automatically includes a match any condition, meaning it applies if no previous rules matched.

  7. Configure Authorization ACL shortcuts in Caddyfile

    main

    The caddy-security plugin provides a shorthand syntax in the Caddyfile to define Authorization Access Control List (ACL) rules. These shortcuts allow you to quickly define rules based on fields, HTTP methods, and request paths using the allow or deny directives.

    Syntax Patterns

    Rules are constructed using a sequence of arguments that transition through different modes:

    1. Field Match (Default): Starts with the field name or a wildcard (* or any).
    2. Method Match: Use the with keyword followed by the HTTP method (e.g., GET, POST).
    3. Path Match: Use the to keyword followed by the path pattern.

    Directive Actions

    • allow: Sets the rule action to allow, logs the event, and uses debug level logging.
    • deny: Sets the rule action to deny, stops processing further rules, and logs the event with a warn level.

    Examples

    Allow any request with a specific field: allow any (matches if the field exists) allow user_id (matches if user_id matches the provided value)

    Allow specific method and path: allow user_id with GET to /api/v1/*

    Deny specific method and path: deny POST to /admin

  8. Use the authenticate directive in Caddyfile

    main

    The authenticate directive allows you to apply authentication via a specific portal to certain routes. It supports two syntax patterns in the Caddyfile:

    1. Global matching: authenticate with <portal_name> (matches all routes by default).
    2. Specific route matching: authenticate <route_matcher> with <portal_name>.

    The <route_matcher> is used to determine which requests are subject to the authentication portal. The <portal_name> must correspond to a portal configured within the security app.

  9. Configure miscellaneous authorization settings in Caddyfile

    main

    The security plugin for Caddy allows configuring various miscellaneous authorization settings within a Caddyfile using specific sub-directives under an authorization policy. These settings control behaviors like cookie names, token sources, validation methods, and authentication redirects.

    Available sub-directives are grouped by their primary action: enable, validate, disable, set, and with.

  10. Configure the Authentication Portal UI in Caddyfile

    main

    The caddy-security plugin allows you to customize the appearance and behavior of the authentication portal via Caddyfile subdirectives. You can configure themes, languages, logos, metadata, custom assets (CSS/JS), and navigation links.

    Available Subdirectives

    SubdirectiveArguments / FormatDescription
    theme<value>Sets the UI theme.
    language<value>Sets the UI language.
    logourl <path> or description <text>Sets the logo URL or its description.
    metatitle <text>, author <text>, or description <text>Sets HTML meta tags for SEO and social sharing.
    auto_redirect_url<url>The URL to redirect to automatically.
    template<type> <path>Maps a template type to a specific file path.
    customcss <path>, js <path>, or html header path <path>Injects custom CSS, JS, or HTML header content.
    static_asset<uri> <content_type> <fs_path>Registers a static asset. The URI must start with assets/.
    links(Block)Defines a list of navigation links.

    Configuring Links

    The links directive uses a block format. Each link can have optional modifiers:

    • target_blank: Opens the link in a new tab.
    • icon <name>: Adds a specific icon to the link.
    • disabled: Prevents the link from being rendered.

    Example link syntax:

    links {
    Privacy Policy https://example.com/privacy target_blank
    Help https://example.com/help icon help-circle
    Hidden Link https://example.com/hidden disabled
}

  11. Map tokens to cookies using the `set` directive

    main

    The set directive allows you to map specific authentication tokens to a named cookie. This is useful for client-side access to tokens.

    Syntax: set <session_id|redirect_url|sandbox_id|id_token|access_token|refresh_token> cookie name <name>

  12. Configure user registration in Caddyfile

    main

    The user registration directive allows you to configure identity provider settings and user registration requirements within a Caddyfile. It uses a block syntax where you can define titles, verification codes, domain requirements, email providers, and administrative contacts.

    Supported sub-directives include:

    • title <name>: Sets the registration title.
    • code <name>: Sets the registration code.
    • dropbox <path>: Sets the dropbox path.
    • require accept terms: Requires users to accept terms.
    • require domain mx: Requires the domain to have MX records.
    • email provider <name>: Specifies the email provider.
    • admin email <email_address_1> <<email_address_N>: Defines administrative email addresses.
    • identity store <name>: Specifies the identity store.
    • link terms <url>: Provides a URL for terms of service.
    • link privacy <url>: Provides a URL for the privacy policy.
    • <allow|deny> [exact|partial|prefix|suffix|regex] domain <string>: Controls domain access using various matching modes.
    user registration <name> {
  title <name>
  code <name>
  dropbox <path>
  require accept terms
  require domain mx
  email provider <name>
  admin email <email_address_1> <<email_address_N>
  identity store <name>
  link terms <url>
  link privacy <url>
  <allow|deny> [exact|partial|prefix|suffix|regex] domain <string>
}