SSSD Manual pages

Table of Contents

sssd-secrets — SSSD Secrets responder


sssd-secrets — SSSD Secrets responder


This manual page describes the configuration of the Secrets responder for sssd(8). For a detailed syntax reference, refer to the FILE FORMAT section of the sssd.conf(5) manual page.

Many system and user applications need to store private information such as passwords or service keys and have no good way to properly deal with them. The simple approach is to embed these secrets into configuration files potentially ending up exposing sensitive key material to backups, config management system and in general making it harder to secure data.

The custodia project was born to deal with this problem in cloud like environments, but we found the idea compelling even at a single system level. As a security service, SSSD is ideal to host this capability while offering the same API via a Unix Socket. This will make it possible to use local calls and have them transparently routed to a local or a remote key management store like IPA Vault for storage, escrow and recovery.

The secrets are simple key-value pairs. Each user's secrets are namespaced using their user ID, which means the secrets will never collide between users. Secrets can be stored inside containers which can be nested.


The UNIX socket the SSSD responder listens on is located at /var/run/secrets.socket.

The secrets responder is socket-activated by systemd(1). Unlike other SSSD responders, it cannot be started by adding the secrets string to the service directive. The systemd socket unit is called sssd-secrets.socket and the corresponding service file is called sssd-secrets.service. In order for the service to be socket-activated, make sure the socket is enabled and active and the service is enabled:

systemctl start sssd-secrets.socket
systemctl enable sssd-secrets.socket
systemctl enable sssd-secrets.service

Please note your distribution may already configure the units for you.


The generic SSSD responder options such as debug_level or fd_limit are accepted by the secrets responder. Please refer to the sssd.conf(5) manual page for a complete list. In addition, there are some secrets-specific options as well.

provider (string)

This option specifies where should the secrets be stored. The secrets responder can configure a per-user subsections that define which provider store the secrets for this particular user. The per-user subsections should contain all options for that user's provider. If a per-user section does not exist, the global settings from the secret responder's section are used. The following providers are supported:


The secrets are stored in a local database, encrypted at rest with a master key. The local provider does not have any additional config options at the moment.


The secrets responder forwards the requests to a Custodia server. The proxy provider supports several additional options (see below).

Default: local

containers_nest_level (integer)

This option specifies the maximum allowed number of nested containers.

Default: 4

max_secrets (integer)

This option specifies the maximum number of secrets that can be stored.

Default: 1024

The following options are only applicable for configurations that use the proxy provider.

proxy_url (string)

The URL the Custodia server is listening on. At the moment, http and https protocols are supported.

The format of the URI must match the format defined in RFC 2732:


Example: http://localhost:8080

auth_type (string)

The method to use when authenticating to a Custodia server. The following authentication methods are supported:


Authenticate with a username and a password as set in the username and password options.


Authenticate with HTTP header value as defined in the auth_header_name and auth_header_value configuration options.

auth_header_name (string)

If set, the secrets responder would put a header with this name into the HTTP request with the value defined in the auth_header_value configuration option.


auth_header_value (string)

The value sssd-secrets would use for the auth_header_name.

Example: mysecret

forward_headers (list of strings)

The list of HTTP headers to forward to the Custodia server together with the request.

Default: not set


This section lists the available commands and includes examples using the curl(1) utility. All requests towards the proxy provider must set the Content Type header to application/json. In addition, the local provider also supports Content Type set to application/octet-stream. Secrets stored with requests that set the Content Type header to application/octet-stream are base64-encoded when stored and decoded when retrieved, so it's not possible to store a secret with one Content Type and retrieve with another. The secret URI must begin with /secrets/.

Listing secrets

To list the available secrets, send a HTTP GET request with a trailing slash appended to the container path.


curl -H "Content-Type: application/json" \
     --unix-socket /var/run/secrets.socket \
     -XGET http://localhost/secrets/

Retrieving a secret

To read a value of a single secret, send a HTTP GET request without a trailing slash. The last portion of the URI is the name of the secret.


curl -H "Content-Type: application/json" \
     --unix-socket /var/run/secrets.socket \
     -XGET http://localhost/secrets/foo

curl -H "Content-Type: application/octet-stream" \
     --unix-socket /var/run/secrets.socket \
     -XGET http://localhost/secrets/bar

Setting a secret

To set a secret using the application/json type, send a HTTP PUT request with a JSON payload that includes type and value. The type should be set to "simple" and the value should be set to the secret value. If a secret with that name already exists, the response is a 409 HTTP error.

The application/json type just sends the secret as the message payload.

The following example sets a secret named 'foo' to a value of 'foosecret' and a secret named 'bar' to a value of 'barsecret' using a different Content Type.

curl -H "Content-Type: application/json" \
     --unix-socket /var/run/secrets.socket \
     -XPUT http://localhost/secrets/foo \

curl -H "Content-Type: application/octet-stream" \
     --unix-socket /var/run/secrets.socket \
     -XPUT http://localhost/secrets/bar \

Creating a container

Containers provide an additional namespace for this user's secrets. To create a container, send a HTTP POST request, whose URI ends with the container name. Please note the URI must end with a trailing slash.

The following example creates a container named 'mycontainer':

curl -H "Content-Type: application/json" \
     --unix-socket /var/run/secrets.socket \
     -XPOST http://localhost/secrets/mycontainer/

To manipulate secrets under this container, just nest the secrets underneath the container path:


Deleting a secret or a container

To delete a secret or a container, send a HTTP DELETE request with a path to the secret or the container.

The following example deletes a secret named 'foo'.

curl -H "Content-Type: application/json" \
     --unix-socket /var/run/secrets.socket \
     -XDELETE http://localhost/secrets/foo


For testing the proxy provider, you need to set up a Custodia server to proxy requests to. Please always consult the Custodia documentation, the configuration directives might change with different Custodia versions.

This configuration will set up a Custodia server listening on http://localhost:8080, allowing anyone with header named MYSECRETNAME set to mysecretkey to communicate with the Custodia server. Place the contents into a file (for example, custodia.conf):

server_version = "Secret/0.0.7"
server_url = http://localhost:8080/
auditlog = /var/log/custodia.log
debug = True

handler =
dburi = /var/lib/custodia.db
table = secrets

handler = custodia.httpd.authenticators.SimpleHeaderAuth
value = mysecretkey

handler = custodia.httpd.authorizers.SimplePathAuthz
paths = /secrets

handler = custodia.root.Root
store = simple

Then run the custodia command, pointing it at the config file as a command line argument.

Please note that currently it's not possible to proxy all requests globally to a Custodia instance. Instead, per-user subsections for user IDs that should proxy requests to Custodia must be defined. The following example illustrates a configuration, where the user with UID 123 would proxy their requests to Custodia, but all other user's requests would be handled by a local provider.


provider = proxy
proxy_url = http://localhost:8080/secrets/
auth_type = header
auth_header_name = MYSECRETNAME
auth_header_value = mysecretkey