Protect Content¶

Pulp provides a way to protect content from being accessed by unauthorized users. This is done by associating a ContentGuard with a distribution.

When a ContentGuard is associated with a distribution, Pulp will check that the user has the correct permissions to access the content. If the setting HIDE_GUARDED_DISTRIBUTIONS is set to True, then distributions guarded by a ContentGuard will not be shown in the directory listing in the content app.

Available Content Guards¶

Pulp offers several content guard types to protect your distributions:

RBAC Content Guard¶

The RBAC (Role-Based Access Control) content guard protects distributions using Pulp's built-in authentication and authorization system. Users must authenticate using their Pulp credentials and have appropriate permissions to access protected content.

To set up an RBAC content guard:

Create the content guard:

pulp content-guard rbac create --name rbac-guard

Assign permissions to users and/or groups:

pulp content-guard rbac assign --name rbac-guard --user alice --user bob --group file-buddies

Associate the content guard with a distribution:

pulp file distribution update --name foo --content-guard core:rbac:rbac-guard

By default, users/groups need the core.download_rbaccontenguard permission to access protected content.

X509 Certificate Guard¶

The X509 certificate guard (from pulp-certguard) protects distributions using x509 client certificates. Users must present a valid certificate to access protected content. Follow the pulp-certguard quickstart guide to configure this guard.

RHSM Certificate Guard¶

The RHSM certificate guard (from pulp-certguard) validates certificates created using python-rhsm.

Warning

This guard is currently not recommended as python-rhsm has not been updated recently.

Header Content Guard¶

The header content guard checks for specific HTTP headers in incoming requests. This guard is primarily useful in custom setups where a reverse proxy adds authentication/authorization headers before forwarding requests to Pulp.

# Create a header content guard that only accepts requests with the X-Pulp-User header set to alice
pulp content-guard header create --name header-guard --header-name X-Pulp-User --header-value alice

# Use a JQ filter to extract the value to check against from the header
pulp content-guard header create --name header-guard --header-name X-Auth-Service --header-value true --jq-filter '.authenticated'

EnvVar Header Content Guard¶

The env-var header content guard checks a request header against a secret stored in a content-app environment variable. Proxies must send base64(utf-8(secret)) in the configured header. Pulp reads the plaintext secret from the content app at request time, so rotating the secret is a deployment change rather than a database update.

The environment variable name must be listed in ENVVAR_HEADER_CONTENT_GUARD_ALLOWED_VARS. Creating this guard is privileged: the name is a pointer into the content-app process environment, so this type should not be granted to untrusted tenants.

Set the secret on every content-app replica (and typically the API as well). Setting it only on the API causes all content requests to repositories using this kind of ContentGuard to be denied.

Pulp CLI commands for this guard type are not available yet. Use the REST API:

# Allow the env var, then create a guard that checks X-Pulp-Shared-Secret against it
# ENVVAR_HEADER_CONTENT_GUARD_ALLOWED_VARS = ["SHARED_SECRET"]
export GUARD_HREF=$(curl -s -X POST :24817/pulp/api/v3/contentguards/core/envvar_header/ \
  -H "Content-Type: application/json" \
  -d '{"name": "shared-secret-guard", "header_name": "X-Pulp-Shared-Secret", "env_var": "SHARED_SECRET"}' \
  | jq -r '.pulp_href')

# Assign it to an existing file distribution (DISTRO_HREF is that distribution's pulp_href)
curl -s -X PATCH :24817${DISTRO_HREF} \
  -H "Content-Type: application/json" \
  -d "{\"content_guard\": \"${GUARD_HREF}\"}"

Composite Content Guard¶

The composite content guard combines multiple guards using OR logic - if any of the configured guards allows access, the request is permitted. This enables flexible authentication schemes, like allowing access via either certificates OR RBAC authentication.

# Use different types of content guards, e.g. RBAC and X509
pulp content-guard composite create --name composite-guard --guard core:rbac:rbac-guard --guard core:x509:x509-guard

Redirect Content Guard¶

The redirect content guard validates pre-signed URLs generated by Pulp. This guard is primarily used internally by certain plugins (like pulp-container) and is not intended for direct configuration by users.

Domain Default Content Guard¶

When domains are enabled, each domain can have a default_content_guard that is automatically assigned to new distributions created within that domain. This removes the need to specify a content guard on every distribution and ensures that content is protected by default.

The domain default is applied when:

A distribution is created without an explicit content_guard.
The domain has a default_content_guard configured.

An explicitly provided content_guard on a distribution always takes precedence over the domain default.

Note

Setting or changing the domain default does not affect distributions that already exist — only new distributions created after the default is set will inherit it.

Setting Up a Domain Default¶

The default_content_guard can only be set on an existing domain because the content guard must belong to the same domain. Create the domain first, then update it:

# Create a content guard in the domain
pulp --domain mydomain content-guard rbac create --name default-guard

# Assign permissions
pulp --domain mydomain content-guard rbac assign --name default-guard --user alice

# Set it as the domain default
pulp --domain mydomain domain update --name mydomain \
  --default-content-guard core:rbac:default-guard

From this point on, any distribution created in mydomain without an explicit content_guard will automatically receive default-guard.

Using a Composite Guard as Default¶

To apply multiple guards by default, create a composite content guard and set it as the domain default:

pulp --domain mydomain content-guard composite create --name multi-guard \
  --guard core:rbac:rbac-guard --guard core:x509:x509-guard

pulp --domain mydomain domain update --name mydomain \
  --default-content-guard core:composite:multi-guard

Removing the Default¶

Clear the domain default so new distributions are no longer auto-guarded:

pulp --domain mydomain domain update --name mydomain \
  --default-content-guard ""

Note

Removing or changing the domain default does not affect distributions that already have a content guard assigned.