.. _deploy-cephadm-oauth2-proxy:

================== OAuth2 Proxy

Deploying oauth2-proxy

In Ceph releases starting from Tentacle, 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:

.. prompt:: bash #

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 <https://oauth2-proxy.github.io/oauth2-proxy/configuration/providers/>_ 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 the oauth2-proxy service, please remember to deploy the mgmt-gateway service by turning on the --enable_auth flag, i.e.:

.. prompt:: bash #

ceph orch apply mgmt-gateway --enable_auth=true

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

.. code-block:: yaml

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 <https://oauth2-proxy.github.io/oauth2-proxy/>_ project documentation.

.. py:currentmodule:: ceph.deployment.service_spec

.. autoclass:: OAuth2ProxySpec :members:

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-proxy service.

.. prompt:: bash #

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:

.. code-block:: bash

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