OAuth2 Proxy

Deploying oauth2-proxy

In Ceph releases starting from Squid, the oauth2-proxy service introduces an advanced method for managing authentication and access control for Ceph applications. This service integrates with external Identity Providers (IDPs) to provide secure, flexible authentication via the OIDC (OpenID Connect) protocol. oauth2-proxy acts as an authentication gateway, ensuring that access to Ceph applications including the Ceph Dashboard and monitoring stack is tightly controlled.

To deploy the oauth2-proxy service, use the following command:

ceph orch apply oauth2-proxy [--placement ...] ...

Once applied, cephadm will re-configure the necessary components to use oauth2-proxy for authentication, thereby securing access to all Ceph applications. The service will handle login flows, redirect users to the appropriate IDP for authentication, and manage session tokens to facilitate seamless user access.

Benefits of the oauth2-proxy service

Enhanced Security: Provides robust authentication through integration with external IDPs using the OIDC protocol.
Seamless SSO: Enables seamless single sign-on (SSO) across all Ceph applications, improving user access control.
Centralized Authentication: Centralizes authentication management, reducing complexity and improving control over access.

Security enhancements

The oauth2-proxy service ensures that all access to Ceph applications is authenticated, preventing unauthorized users from accessing sensitive information. Since it makes use of the oauth2-proxy open source project, this service integrates easily with a variety of external IDPs to provide a secure and flexible authentication mechanism.

High availability

In general, oauth2-proxy is used in conjunction with the mgmt-gateway. The oauth2-proxy service can be deployed as multiple stateless instances, with the mgmt-gateway (nginx reverse-proxy) handling load balancing across these instances using a round-robin strategy. Since oauth2-proxy integrates with an external identity provider (IDP), ensuring high availability for login is managed externally and not the responsibility of this service.

Accessing services with oauth2-proxy

After deploying oauth2-proxy, access to Ceph applications will require authentication through the configured IDP. Users will be redirected to the IDP for login and then returned to the requested application. This setup ensures secure access and integrates seamlessly with the Ceph management stack.

Service Specification

Before deploying oauth2-proxy service please remember to deploy the mgmt-gateway service by turning on the --enable_auth flag. i.e:

ceph orch apply mgmt-gateway --enable_auth=true

An oauth2-proxy service can be applied using a specification. An example in YAML follows:

service_type: oauth2-proxy
service_id: auth-proxy
placement:
  label: mgmt
spec:
 https_address: "0.0.0.0:4180"
 provider_display_name: "My OIDC Provider"
 client_id: "your-client-id"
 oidc_issuer_url: "http://192.168.100.1:5556/dex"
 client_secret: "your-client-secret"
 cookie_secret: "your-cookie-secret"
 ssl_certificate: |
   -----BEGIN CERTIFICATE-----
   MIIDtTCCAp2gAwIBAgIYMC4xNzc1NDQxNjEzMzc2MjMyXzxvQ7EcMA0GCSqGSIb3
   DQEBCwUAMG0xCzAJBgNVBAYTAlVTMQ0wCwYDVQQIDARVdGFoMRcwFQYDVQQHDA5T
   [...]
   -----END CERTIFICATE-----
ssl_certificate_key: |
   -----BEGIN PRIVATE KEY-----
   MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQC5jdYbjtNTAKW4
   /CwQr/7wOiLGzVxChn3mmCIF3DwbL/qvTFTX2d8bDf6LjGwLYloXHscRfxszX/4h
   [...]
   -----END PRIVATE KEY-----

Fields specific to the spec section of the oauth2-proxy service are described below. More detailed description of the fields can be found on oauth2-proxy project documentation.

class ceph.deployment.service_spec.OAuth2ProxySpec(service_type='oauth2-proxy', service_id=None, config=None, networks=None, placement=None, https_address=None, provider_display_name=None, client_id=None, client_secret=None, oidc_issuer_url=None, redirect_url=None, cookie_secret=None, ssl_certificate=None, ssl_certificate_key=None, allowlist_domains=None, unmanaged=False, extra_container_args=None, extra_entrypoint_args=None, custom_configs=None)

client_id: The client ID for authenticating with the identity provider.

client_secret: The client secret for authenticating with the identity provider.

https_address: The address for HTTPS connections, formatted as ‘host:port’.

networks: List[str]: A list of network identities instructing the daemons to only bind on the particular networks in that list. In case the cluster is distributed across multiple networks, you can add multiple networks. See Networks and Ports, Specifying Networks and Specifying Networks.

oidc_issuer_url: The URL of the OpenID Connect (OIDC) issuer.

placement: PlacementSpec: See Daemon Placement.

provider_display_name: The display name for the identity provider (IDP) in the UI.

ssl_certificate: The multi-line SSL certificate for encrypting communications.

ssl_certificate_key: The multi-line SSL certificate private key for decrypting communications.

The specification can then be applied by running the below command. Once becomes available, cephadm will automatically redeploy the mgmt-gateway service while adapting its configuration to redirect the authentication to the newly deployed oauth2-service.

ceph orch apply -i oauth2-proxy.yaml

Limitations

A non-exhaustive list of important limitations for the oauth2-proxy service follows:

High-availability configurations for oauth2-proxy itself are not supported.
Proper configuration of the IDP and OAuth2 parameters is crucial to avoid authentication failures. Misconfigurations can lead to access issues.

Container images

The container image the oauth2-proxy service will use can be found by running:

ceph config get mgr mgr/cephadm/container_image_oauth2_proxy

Admins can specify a custom image to be used by changing the container_image_oauth2_proxy cephadm module option. If there were already running daemon(s), you must also redeploy the daemon(s) for them to use the new image.

For example:

ceph config set mgr mgr/cephadm/container_image_oauth2_proxy <new-oauth2-proxy-image>
ceph orch redeploy oauth2-proxy

Brought to you by the Ceph Foundation

The Ceph Documentation is a community resource funded and hosted by the non-profit Ceph Foundation. If you would like to support this and our other efforts, please consider joining now.