keycloak-httpd-client-install - Man Page

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

-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-install/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 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 BDetermining which authentication role to use topics for 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: [])

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

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

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

realm-admin

root-admin

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:

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

• * root-admin
• * realm-admin

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.

* Set up template environment

* Set up X509 Certificiates.

* Build the mod_auth_openidc or mod_auth_mellon httpd config file.

* Build the client's protocol description

Add the httpd client to the Keycloak server.

* Connect to Keycloak Server.

* Query realms from Keycloak server, optionally create new realm.

* Query realm clients from Keycloak server, optionally delete existing.

* Create new client in Keycloak realm.

* Adjust client configuration

* Add attributes to be returned in assertion

* Retrieve IdP metadata from Keycloak server.

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.

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.

John Dennis <jdennis@redhat.com>