keycloak-h...ent-install(1)

📦 version 1.3, in centos-stream 10, centos-stream 9, fedora 43, fedora 44

💖 NAME 💖

keycloak-httpd-client-install — tools to configure Apache HTTPD as a Keycloak client. 🦋

And yes bestie, this is the keycloak-h...ent-install(1) page from the General Commands Manual — the name got squished in the header but it's the same icon, don't worry. ✨

🌈 SYNOPSIS 🌈

keycloak-httpd-client-install --app-name APP_NAME -s | --keycloak-server-url KEYCLOAK_SERVER_URL -r | --keycloak-realm KEYCLOAK_REALM -l | --protected-locations PROTECTED_LOCATIONS [ options ]

Configure mod_auth_mellon or mod_auth_openidc as a Keycloak client. That's the whole vibe. 👑

✨ OPTIONS ✨

  • -h, --help — show this help message and exit. classic. 💅
  • --version — display version and exit.
  • --no-root-check — permit running by non-root (default: False). normally it wants root, this is the permission slip.
  • -v, --verbose — be chatty (default: False). give me the yapping, i want it.
  • -d, --debug — turn on debug info (default: False).
  • --show-traceback — exceptions print traceback in addition to error message (default: False). for when you NEED the receipts.
  • --log-file LOG_FILE — log file pathname (default: /var/log/python-keycloak-httpd-client/keycloak-httpd-client-install.log).
  • --app-name APP_NAME — name of the web app being protected by mod_auth_mellon (default: None).
  • --force — forcefully override safety checks (default: False). she's forceful for a reason, be careful bestie.
  • --permit-insecure-transport — normally secure transport such as TLS is required, this defeats that check (default: False). it literally says insecure in the name. it's giving bad idea energy.
  • --tls-verify — TLS certificate verification for requests to the server. May be one of case insenstive [true, yes, on] to enable, [false, no, off] to disable. Or the pathname to a OpenSSL CA bundle to use. (default: True).

🎀 Program Configuration: 🎀

  • --template-dir TEMPLATE_DIR — Template location (default: /usr/share/keycloak-httpd-client-install/templates).
  • --httpd-dir HTTPD_DIR — Template location (default: /etc/httpd). (yes it says "Template location" again, that's what the man page says, i'm not editing the queen's words)

💜 Keycloak IdP: 💜

  • -r, --keycloak-realm KEYCLOAK_REALM — realm name (default: None).
  • -s, --keycloak-server-url KEYCLOAK_SERVER_URL — Keycloak server URL (default: None).
  • -a, --keycloak-auth-role root-admin|realm-admin|anonymous — authenticating as what type of user (default: root-admin).
  • -u, --keycloak-admin-username KEYCLOAK_ADMIN_USERNAME — admin user name (default: admin).
  • -P, --keycloak-admin-password-file KEYCLOAK_ADMIN_PASSWORD_FILE — file containing the admin password (or use a hyphen "-" to indicate the password will be read from stdin) (default: None). this is the safe way, take notes 📝
  • --keycloak-admin-realm KEYCLOAK_ADMIN_REALM — realm admin belongs to (default: master).
  • --initial-access-token INITIAL_ACCESS_TOKEN — realm initial access token for client registeration (default: None).
  • --client-originate-method native|registration — The method used on the Keycloak REST interface for creating a new client. There are two possibilities:
    • native — A Keycloak clientRespresentation JSON object is sent to the Keycloak client REST endpoint. This is a native Keycloak data format understood only by Keycloak and as such permits setting values unique to Keycloak. This is sometimes refered to as the default client data format.
    • registration — The data used to create the client is sent to the Keycloak registration endpoint. The data format depends on the type of client being created and can be controlled by the --client-data-format. The registration method has the advantage of not requiring admin privileges, see the Authentication Levels and Permissions and 0 details.

(default: native)

  • --client-data-format CLIENT_DATA_FORMAT — Must be one of default|oidc|saml2. When using the registration client originate method this selects the type of data used to create the client. For OIDC it can be either default to use Keycloak's clientRespresentation JSON object or oidc for the OpenID Connect Dynamic Client Registration JSON object. For OIDC it defaults to default. For SAML it must be saml2.) (default: default)
    • default — A Keycloak clientRepresentation JSON Object sent to the /realms/{realm}/clients-registrations/default endpoint.
    • oidc — A OIDC Dynamic Client Registeration JSON object sent to the /realms/{realm}/clients-registrations/openid-connect endpoint.
    • saml2 — A SAML metadata entity descriptor in XML format sent to the /realms/{realm}/clients-registrations/saml2-entity-descriptor endpoint.

🌸 Common Client Options 🌸

  • -t, --client-type openidc|mellon — Which kind of client. For mod_auth_openidc use "openidc". For mod_auth_mellon use "mellon". pick your fighter 💫
  • --clientid CLIENTID — The clientid Keycloak identifies the client by. This has different meanings depending on the type of client:
    • SAML — It is the EntityID and defaults to {client_https_url}/{mellon_root}/{mellon_endpoint_path}/metadata)
    • OIDC — It is the clientid and defaults to {client_hostname}-{app_name}
  • --client-hostname CLIENT_HOSTNAME — The fully qualified host name the client is running on or responds to.
  • --client-https-port CLIENT_HTTPS_PORT — SSL/TLS port used to connect to client.
  • --crypto-passphrase CRYPTO_PASSPHRASE — Used to encrypt cookies, cache data, etc. If not supplied a random string will be generated. she's got a random string for you if you don't bring your own 🔐
  • --location-root LOCATION_ROOT — Common root ancestor for all protected locations.

🦋 mod_auth_oidc OIDC RP Client Options 🦋

  • --oidc-redirect-uri OIDC_REDIRECT_URI — The OIDC redirect_uri. Must be an antecedent (i.e. child) of one of the protected locations. (default: The first protected location appened with "/redirect_uri")
  • --oidc-logout-uri OIDC_REDIRECT_URI — Can be used to add the location the user is redirected to after logout as an additional redirectUri value in Keycloak's client representation. The location should not be nested under any of the protected locations, otherwise the login process would start again. (default: None). do NOT nest it, she will loop forever, that's not the vibe 😭
  • --oidc-client-secret OIDC_CLIENT_SECRET — OIDC client secret (default: generated random string).
  • --oidc-remote-user-claim OIDC_REMOTE_USER_CLAIM — claim used when setting the REMOTE_USER variable (default: "sub").

⭐ mod_auth_mellon SP Client Options ⭐

  • --mellon-key-file MELLON_KEY_FILE — certficate key file (default: None).
  • --mellon-cert-file MELLON_CERT_FILE — certficate file (default: None).
  • --mellon-endpoint MELLON_ENDPOINT — Used to form the MellonEndpointPath, e.g. {mellon_root}/{mellon_endpoint} (default: mellon).
  • --mellon-idp-attr-name MELLON_IDP_ATTR_NAME — Name of the attribute mod_auth_mellon adds which will contain the IdP entity id (default: {client_https_url}/{mellon_root}/{mellon_endpoint_path}/metadata)
  • --mellon-organization-name MELLON_ORGANIZATION_NAME — Add SAML OrganizationName to SP metadata (default: None).
  • --mellon-organization-display-name MELLON_ORGANIZATION_DISPLAY_NAME — Add SAML OrganizationDisplayName to SP metadata (default: None).
  • --mellon-organization-url MELLON_ORGANIZATION_URL — Add SAML OrganizationURL to SP metadata (default: None).
  • -l, --protected-locations PROTECTED_LOCATIONS — Web location to be protected by client. May be specified multiple times (default: []). stack it up, she takes multiples 💅

💀 DEPRECATED OPTIONS 💀

bestie. these are old. they still exist but they are over. use the new ones, i'm begging. 🙈
  • -p, --keycloak-admin-password — It is insecure to pass a password on the command line. Use one of the other methods detailed in the How to pass the Keycloak admin password topic. literally everyone can see it in your process list. no. stop.
  • --mellon-protected-locations — Use -l or --protected-locations instead.
  • --mellon-hostname — Use --client-hostname instead.
  • --mellon-https-port — Use --client-https-port instead.
  • --mellon-root — Use --location-root instead.
  • --mellon-entity-id — Use --clientid instead.

✨ DESCRIPTION ✨

keycloak-httpd-client-install is the little helper that configures an httpd (that's Apache, bestie) instance as a client of the Keycloak Identity Provider (IdP) — using either the mod_auth_openidc or the mod_auth_mellon authentication module. The whole reason we're here? Serving up authentication and authorization services to your web applications. It's giving infrastructure, it's giving ✨ security ✨.

🚀 Quick Start

Okay so despite the absolute wealth of options this tool hands you, you can literally just run it with a minimum of 4 little pieces of information:

  • an application name
  • a web resource to protect (like a location)
  • the Keycloak server and realm
  • Keycloak authentication credentials

💖 Simple Example

sudo keycloak-httpd-client-install \
    --app-name foo \
    --protected-location /private \
    --keycloak-server-url keycloak.example.com \
    --keycloak-realm my_organization \
    --keycloak-admin-password-file admin_passwd
🫶 heads up: by default mod_auth_openidc is what gets configured as the client. Wanna do mod_auth_mellon instead? Just add this option and you're so set: --client-type mellon.

🔑 How to pass the Keycloak admin password

You can hand the Keycloak admin password over in any of the ways listed below — and this is the exact order the tool goes looking for it:

  1. It tries the --keycloak-admin-password-file argument first. If it's a hyphen -, the password gets read from stdin. Otherwise the argument is treated as the name of a file, the file gets opened, and the password is read from the file. 🎀
  2. Then it tests whether the KEYCLOAK_ADMIN_PASSWORD environment variable exists. If KEYCLOAK_ADMIN_PASSWORD is defined, the password is read from it.
  3. Then it prompts for the password from the terminal.
😭 bestie the numbers go 1, 2, 4. No, we don't know where 3 went. We simply keep it real and keep it canon. Moving on 💅

👑 Authentication Levels and Permissions

This tool is capable of a whole range of configuration steps, but the extent of those operations can be circumscribed by the privilege level (authorization) the tool is run with. That privilege level is determined by the --keycloak-auth-role command line option, which may be one of these:

  • root-admin — the Keycloak installation has a super realm normally called master, and that's the container for all realms hosted by the Keycloak instance. A user with administration privileges in the master realm can perform all operations on all realms hosted by the instance. Think of such a user as a root user, or root admin. 👑
  • realm-admin — each subordinate realm in the Keycloak instance may have its own administrator(s), and their privileges are restricted exclusively to that realm.
  • anonymous — the tool doesn't authenticate as a user, so no privileges are granted by virtue of being anyone. Any privilege comes by virtue of an initial access token passed in via the -initial-access-token command line option. Think of an initial access token as a one time password scoped to a specific realm. The initial access token has to be generated by an administrator with sufficient privileges on the realm and given to the user of the tool. And the privileges that token confers are limited to registering the client in the realm utilizing the Keycloak client registration service.

Selecting which authentication role gets used is determined by a combination of the --keycloak-auth-role option and the --keycloak-admin-realm option. When the authentication role is one of root-admin or realm-admin, the tool authenticates as a user in a specific realm — and the --keycloak-admin-realm option declares the realm that administrator will authenticate to. For the root-admin role this is typically the master realm. For the realm-admin role this would be the realm the tool is registering the client in.

🧠 Determining which authentication role to use

In general, the principle of least privilege should apply — grant the tool the least privilege necessary to perform the required action. In order of least privilege to greatest privilege, here are the operations possible under the defined authentication roles:

anonymous

  • Can register the client using only the Keycloak client registration service. The tool cannot determine a prori if the client already exists in the realm, and it also can't adjust any configuration options on the client. 🙈
  • The realm must pre-exist.

realm-admin

  • Can enumerate the existing clients in the realm to determine if a conflict would occur.
  • Can delete a pre-existing client and replace it with the new client definition if the --force option is supplied.
  • Can modify the client's configuration.
  • Can use either the client registration service or the REST API to create the client.
  • The realm must pre-exist and contain the realm admin user.

root-admin

  • Includes all of the privileged operations conferred by realm-admin.
  • Can enumerate existing realms on the Keycloak instance to verify the existence of the target realm the client is to be installed in.
  • Can create the target realm if it does not exist.

🛠️ Client creation methods

Keycloak offers two methods to add a client to a realm, and you pick between them with the --client-originate-method option. ✨

registration

Originally designed to support the OIDC Dynamic Client Registration service, it can also be used to register clients with Keycloak's default clientRepresentation JSON Object, or SAML SP clients using SAML Entity Descriptor Metadata in XML format — it all depends on the exact endpoint utilized. See --cient-data-formt for details. The primary benefit of the client origination method is that it does not require admin privileges; instead an initial access token issued by the realm admin is used, and this is called anonymous authentication. Selected with --client-originate-method register. 🎀

The client registration service requires the use of an initial access token. For all authentication roles, an initial access token can be provided on the command line via the initial-access-token option. That initial access token will have to have been provided by a Keycloak administrator who pre-creates it. But if the authentication role is either root-admin or realm-admin, the tool has sufficient privilege to obtain an initial access token on its own behalf — which negates the need for a Keycloak admin to supply one externally. Slay.

native

This method sends Keycloak's native clientRepresentation JSON object to the auth/admin/realms/{realm}/clients client endpoint to create or update a client.

If the client is a SAML SP, its Entity Descriptor XML Metadata is first sent to the auth/admin/realms/{realm}/client-description-converter conversion endpoint, which returns a native clientRepresention JSON object derived from the SAML SP metadata. That derived clientRepresentation is subsequently sent to the client REST endpoint.

The client registration service may be used by the following authentication roles:

  • root-admin
  • realm-admin
  • anonymous (requires use of --initial-access-token)

The REST API may be used by the following authentication roles:

  • root-admin
  • realm-admin

✨ OPERATION ✨

okay so bestie, keycloak-httpd-client-install performs the following operational steps which can be grouped into two major operational groups:

  • Configure the httpd client
  • Add the httpd client to the Keycloak server.

Configure the httpd client 💅

  • Create directories. Files written by keycloak-httpd-client-install need a destination directory (see FILES). If the necessary directories are not present they are created.
  • Set up template environment. Many of the files written by keycloak-httpd-client-install are based on jinga2 templates. The default template file location can be overridden with the --template-dir option.
  • Set up X509 Certificiates. Some client configurations require the use of X509 certificates and keys. If these were not supplied as an option a self-signed certificate will be generated.
  • Build the mod_auth_openidc or mod_auth_mellon httpd config file. This is the httpd configuration file which will be installed in Apache's conf.d configuration directory. It contains configuration directives for mod_auth_openidc or mod_auth_mellon depending on which client is being configured.
  • Build the client's protocol description. For mod_auth_openidc this means building JSON object which describes the client. It will be sent to the Keycloak server to add the client to the realm. For mod_auth_mellon this means building the SAML SP XML metadata. The SP metadata is used both by mod_auth_mellon when it initializes and is also sent to the Keycloak server when adding the client to the Keycloak realm.

Add the httpd client to the Keycloak server. 🚀

  • Connect to Keycloak Server. A session is established with the Keycloak server. OAuth2 is used to log in as the admin user using the --keycloak-admin-username and --keycloak-admin-password-file options if you're using admin privileges. Otherwise a non-authenticated (e.g. anonymous) session is established and an initial access token supplied to you by a Keycloak admin will be used to register the client.
  • Query realms from Keycloak server, optionally create new realm. Keycloak supports multi-tenancy, it may present many IdP's each one specified by a Keycloak realm. The --keycloak-realm option identifies which Keycloak realm we will bind to. The Keycloak realm may already exist on the Keycloak server, if it does keycloak-httpd-client-install will use it. If the Keycloak realm does not exist yet it will be created for you.

Requires the root-admin auth role.

  • Query realm clients from Keycloak server, optionally delete existing. Before a new client can be added to the Keycloak realm we must assure it does not conflict with an existing client. If the client is already registered in the Keycloak realm keycloak-httpd-client-install will stop processing and exit with an error unless the --force option is used. --force will cause the existing client on the Keycloak realm to be deleted first so that it can be replaced in the next step.

Requires either the root-admin or realm-admin auth role.

  • Create new client in Keycloak realm. The client description is sent to one of the Keycloak server's REST endpoints to add the client to the realm. The choice of which endpoint is used and the data format sent is a function of the client-originate-method, the auth role and client data format. Most users will simply allow the tool to select the optimal combination.
  • Adjust client configuration. Override default Keycloak client values. This varies by Keycloak release.

Requires either the root-admin or realm-admin auth role.

  • Add attributes to be returned in assertion. The client is configured to return necessary attributes. The added attributes are:
    • Groups user is a member of.

Requires either the root-admin or realm-admin auth role.

  • Retrieve IdP metadata from Keycloak server. The mod_auth_mellon SP needs SAML metadata that describes the Keycloak IdP. The metadata for the Keycloak IdP is fetched from the Keycloak server and stored in a location referenced in the mod_auth_mellon SP httpd configuration file. (see FILES) mod_auth_openidc also needs a description of the Keycloak IdP but unlike mod_auth_mellon it is capable of fetching the Keycloak IdP description automatically via the OIDCProviderMetadataURL directive and periodically refreshing it. Therefore this step is skipped for mod_auth_openidc.

🦋 STRUCTURE 🦋

The overarching organization is to produce a web application. An independent set of mod_auth_openidc or mod_auth_mellon files are created per application and registered with the Keycloak server. This permits multiple indpendent client and/or protected web resources to be handled by one Apache instance. When you run keycloak-httpd-client-install you must supply an application name via the --app-name option.

Within the web application you may protect multiple independent web resources specified via the --protected-locations /xxx option. This will cause a location block similar to this to be generated per location (depending on the client type):

mod_auth_openidc

OIDCClientID ...
OIDCProviderMetadataURL ...
OIDCCryptoPassphrase ...
OIDCClientSecret ...
OIDCRedirectURI ...
OIDCRemoteUserClaim ...

<Location /xxx>
    AuthType openid-connect
    Require valid-user
</Location>

mod_auth_mellon

<Location />
    MellonEnable info
    MellonEndpointPath ...
    MellonSPMetadataFile ...
    MellonSPPrivateKeyFile ...
    MellonSPCertFile ...
    MellonIdPMetadataFile ...
    MellonIdP ...
</Location>

<Location /xxx>
    AuthType Mellon
    MellonEnable auth
    Require valid-user
</Location>

These will be added to the client's HTTPD configuration file.

The location of the client configuration directives in the client configuration file depend on the client type.

  • For mod_auth_openidc the directives are global to the module and hence can be located anywhere outside a location directive. The tool places them at the top of the client configuration file.
  • For mod_auth_mellon the directives must be located in a location block handled by mod_auth_mellon. mod_auth_mellon supports directive inheritance, thus any mod_auth_mellon location block located below in the URL hierarchy will inherit directives from above. To avoid duplicate declarations of mod_auth_mellon directives that can be shared by subsequent mod_auth_mellon location block (and protect against future cut-n-paste errors) the shared common mod_auth_mellon directives are located at the location-root.

🌈 Changes from the previous version 🌈

  • keycloak-httpd-client-install now supports mod_auth_opendic in addition to mod_auth_mellon.
  • Some mod_auth_mellon specific options (e.g. --mellon-*) can be shared with mod_auth_openidc. These were renamed to have a --client-* prefix instead. The previous names continue to work but will emit a deprecaton warning and will be removed in a future release.
  • The --client-originate descriptor method has been renamed to native.
  • The {httpd_dir}/saml2 directory containing SAML data files (e.g. metadata, keys, certs, etc.) has been renamed to {httpd_dir}/federation to better reflect it's use as a location to store data used in federated authentication.

🌸 FILES 🌸

So like, here's literally everything keycloak-httpd-client-install creates when you run it, bestie. Manifest time 💅

Directories and files created by running keycloak-httpd-client-install:

  • {httpd_dir}/federation — this dir holds the data files that get used while federated auth is happening. It's the SP's little stash 🎀
  • {httpd_dir}/conf.d/{app_name}_mellon_keycloak_{realm}.conf — THE main mod_auth_mellon config file for your app. It binds to the Keycloak realm IdP, and it's generated from the mellon_httpd.conf template file. Main character energy fr ✨
  • {httpd_dir}/federation/{app_name}.cert — the mod_auth_mellon SP X509 certificate file, in PEM format 📜
  • {httpd_dir}/federation/{app_name}.key — the mod_auth_mellon SP X509 key file, also PEM. Guard this one with your life 🔑
  • {httpd_dir}/federation/{app_name}_keycloak_{realm}_idp_metadata.xml — the Keycloak SAML2 IdP metadata file. It gets fetched from the Keycloak server, not made locally 🌐
  • {httpd_dir}/federation/{app_name}_sp_metadata.xml — the mod_auth_mellon SAML2 SP metadata file, generated from the sp_metadata.xml template file 🦋
  • {httpd_dir}/conf.d/{app_name}_oidc_keycloak_{realm}.conf — THE main mod_auth_openidc config file for your app. It binds to the Keycloak realm IdP and is generated from the oidc_httpd.conf template file 👑

Files referenced by keycloak-httpd-client-install when it runs:

  • /usr/share/python-keycloak-httpd-client/templates/* — jinja2 templates 🌈

Log files:

  • /var/log/python-keycloak-httpd-client/keycloak-httpd-client-install.log — the installation log file 🍓

🐛 DEBUGGING 🐛

Okay so if you're confused about something, the --verbose and --debug options bump up how much detail gets dumped on your console. Cute, right?

But ngl, the log file logs everything at the DEBUG level, so it's usually way easier to just go read the log file when you're debugging. See LOGGING below, iykyk 💖

📓 LOGGING 📓

keycloak-httpd-client-install logs all its operations to a rotated log file. You can override the default log file with the --log-file option — no cap 🫶

Every single run of keycloak-httpd-client-install creates a new log file. Any previous log file gets rotated as a numbered version, and it keeps a maximum of 3 previous log files. Periodt.

Logging to the log file happens at the DEBUG level, which includes all HTTP requests and responses — so yeah, extremely useful for debugging. It's giving receipts 💅

🧚 TEMPLATES 🧚

Many of the files generated by keycloak-httpd-client-install come from jinja2 templates, where the tool substitutes in the values it figured out while running. You can override the default template file location with the --template-dir option ✨

  • {template_dir}/mellon_httpd.conf — the template used to generate the httpd configuration file for mod_auth_mellon, i.e. {httpd_dir}/conf.d/{app_name}_mellon_keycloak_{realm}.conf
  • {template_dir}/sp_metadata.tpl — the template used to generate SAML SP Metadata
  • {template_dir}/oidc_httpd.conf — the template used to generate the httpd configuration file for mod_auth_openidc, i.e. {httpd_dir}/conf.d/{app_name}_oidc_keycloak_{realm}.conf
  • {template_dir}/oidc-client-registration.tpl — the template used to generate the OIDC Dynamic Client Registration data sent to Keycloak's client registration endpoint /realms/{realm}/clients-registrations/openid-connect
  • {template_dir}/oidc-client-representation.tpl — the template used to generate the Keycloak clientRepresentation JSON object used to create a new client using native method, or the registration method using the default client data format at the /realms/{realm}/clients-registrations/default endpoint

🚦 EXIT STATUS 🚦

Vibe check on how it ended 👇

  • 0 — SUCCESS ✅
  • 1 — OPERATION_ERROR
  • 2 — CONFIGURATION_ERROR
  • 3 — INSUFFICIENT_PRIVILEGE
  • 4 — COMMUNICATION_ERROR
  • 5 — ALREADY_EXISTS_ERROR

👑 AUTHOR 👑

John Dennis <jdennis@redhat.com> — the legend who wrote all of this, ty for your service 🫡💖

And that's the whole page, bestie, we made it to the end 🎉 The footer of this one just reads keycloak-h...ent-install(1) — yes the name is literally truncated mid-word in the header/footer because it's that long, iconic behavior honestly 😭. No version or date line survived in what we got, so I'm not gonna make one up — but the source is this keycloak-httpd-client-install(1) manual page as shipped, and this was part 4 of 4. Go forth and federate, you absolute icon 🌈💜

📦 where this page comes from