keycloak-httpd-client-install(1)

NAME
keycloak-httpd-client-install - Tools to configure Apache HTTPD as Keycloak client

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 Keycloak client

OPTIONS

-h, --help
    show this help message and exit

--version
    display version and exit

--no-root-check
    permit running by non-root (default: False)

-v, --verbose
    be chatty (default: False)

-d, --debug
    turn on debug info (default: False)

--show-traceback
    exceptions print traceback in addition to error message (default: False)

--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)

--permit-insecure-transport
    Normally secure transport such as TLS is required, defeat this check (default: False)

--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/templates)

--httpd-dir HTTPD_DIR
    Template location (default: /etc/httpd)

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)

--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 registraton endpoint. The data format depends on the type of client being created and can be contolled by the --client-data-format. The registration method has the advantage of not requiring admin privileges, see the Authentication Levels and Permissions and 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".

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

--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)

--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: [])

DEPRECATED OPTIONS

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

--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 used to configure a httpd (Apache) instance using mod_auth_openidc or mod_auth_mellon authentication modules as a client of the Keycloak Identity Provider (IdP) in order to provide authentication and authorization services to web applications.

Quick Start Despite the wealth of options this tool provides it can be run simply needing a minimum of just 4 pieces of information:

* An application name

* A web resource to protect (e.g. 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

Note, by default mod_auth_openidc will be configured as the client. To configure mod_auth_mellon instead add this option: --client-type mellon.

How to pass the Keycloak admin password

The Keycloak admin password may be passed via one of the possible ways listed here in the order the tool looks for the password.

1. Try the --keycloak-admin-password-file argument. If it's a hyphen read the password from stdin, otherwise treat the argument as the name of a file, open the file and read the password from the file.

2. Test for the existence of the KEYCLOAK_ADMIN_PASSWORD environment variable. If the KEYCLOAK_ADMIN_PASSWORD is defined read the password from it.

4. Prompt for the password from the terminal.

Authentication Levels and Permissions

The tool is capable of range of configuration steps. But the extent of those operations may be circumscribed by the privilege level (authorization) the tool is run with. The privilege level is determined by the --keycloak-auth-role command line option which may be one of:

root-admin: The Keycloak installation has a super realm normally called master which is the container for all realms hosted by the Keycloak instance. A user with administration priviliges 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 it's own administrator(s) whose privileges are restricted exclusively to that realm.

anonymous: The tool does not authenticate as a user and hence no priviliges are granted. Any privilege is granted 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 must be generated by an administrator with sufficient priviliges on the realm and given to the user of the tool. The priviliges conferred by the initial access token are limited to registering the client in the realm utilizing the Keycloak client registration service.

Selecting which authencation role will be 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 will authenticate as a user in a specific realm, the --keycloak-admin-realm option declares the realm the administrator will authenticate to. For the root-admin role this is typically the master realm. For the realm-admin role this would be realm the tool is registrating the client in.

Determining which authentication role to use In general the principle of least privilige should apply. Grant to the tool the least privilige necessary to perform the required action. In oder of least privilige to greatest privilige the following operations are 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 nor can it 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 clients 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 priviliged operation conferred by the 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 Selected with --client-originate-method option.

registration
    Originally designed to support the OIDC Dynmaic 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 depending on the exact endpoint utilized. See --cient-data-formt for details. The primary benefit of the client origination method is not requiring admin privileges, rather an initial access token issued by the realm admin is used, this is called anonymous authentication. Selected with --client-originate-method register.

    The client registration service requies the use of an initial access token. For all authentiction roles an initial access token can be provided on the command line via the initial-access-token option. The initial access token will have to have been provided by a Keycloak administrator who pre-creates it. If the authencation role is either root-admin or realm-admin the tool has sufficient privilige to obtain an initial access token on it's behalf negating the need for a Keycloak admin to supply one externally.
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 it's 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. The 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

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
Directories and files created by running keycloak-httpd-client-install:

{httpd_dir}/federation
    This directory contains data files used during federated authentication.

{httpd_dir}/conf.d/{app_name}_mellon_keycloak_{realm}.conf
    This is the primary mod_auth_mellon configuration file for the application. It binds to the Keycloak realm IdP. It is generated from the mellon_httpd.conf template file.

{httpd_dir}/federation/{app_name}.cert
    The mod_auth_mellon SP X509 certficate file in PEM format.

{httpd_dir}/federation/{app_name}.key
    The mod_auth_mellon SP X509 key file in PEM format.

{httpd_dir}/federation/{app_name}_keycloak_{realm}_idp_metadata.xml
    The Keycloak SAML2 IdP metadata file. It is fetched from the Keycloak server.

{httpd_dir}/federation/{app_name}_sp_metadata.xml
    The mod_auth_mellon SAML2 SP metadata file. It is generated from the sp_metadata.xml template file.

{httpd_dir}/conf.d/{app_name}_oidc_keycloak_{realm}.conf
    This is the primary mod_auth_openidc configuration file for the application. It binds to the Keycloak realm IdP. It 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
    Installation log file

DEBUGGING

The --verbose and --debug options can be used to increase the level of detail emitted on the console. However, note the log file logs everything at the DEBUG level so it is usually easier to consult the log file when debugging (see LOGGING)

LOGGING

keycloak-httpd-client-install logs all it's operations to a rotated log file. The default log file can be overridden with the --log-file option. Each run of keycloak-httpd-client-install will create a new log file. Any previous log file will be rotated as a numbered verson keeping a maximum of 3 previous log files. Logging to the log file occurs at the DEBUG level that includes all HTTP requests and responses, this is useful for debugging.

TEMPLATES

Many of the files generated by keycloak-httpd-client-install are produced via jinja2 templates substituting values determined by keycloak-httpd-client-install when it runs. The default template file location can be overridden with the --template-dir option.

{template_dir}/mellon_httpd.conf The template used to generate the httpd configuration file for mod_auth_mellon {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 {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

    0: SUCCESS

    1: OPERATION_ERROR

    2: CONFIGURATION_ERROR

    3: INSUFFICIENT_PRIVILEGE

    4: COMMUNICATION_ERROR

    5: ALREADY_EXISTS_ERROR

AUTHOR
John Dennis <jdennis@redhat.com>