2. EL 8
  3. python3-keycloak-httpd-client-install
  4. keycloak-httpd-client-install(8)

Scroll to navigation

keycloak-httpd-client-install(1) General Commands Manual 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

show this help message and exit
permit running by non-root (default: False)
be chatty (default: False)
turn on debug info (default: False)
exceptions print traceback in addition to error message (default: False)
log file pathname (default: /var/log/python-keycloak-httpd-client/keycloak-httpd-client-install.log)
name of the web app being protected by mod_auth_mellon (default: None)
forcefully override safety checks (default: False)
Normally secure transport such as TLS is required, defeat this check (default: False)
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 location (default: /usr/share/keycloak-httpd-client/templates)
Template location (default: /etc/httpd)

Keycloak IdP:

realm name (default: None)
Keycloak server URL (default: None)
authenticating as what type of user (default: root-admin)
admin user name (default: admin)
file containing the admin password (or use a hyphen "-" to indicate the password will be read from stdin) (default: None)
realm admin belongs to (default: master)
realm initial access token for client registeration (default: None)
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 0 details. (default: native)
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

Which kind of client. For mod_auth_openidc use "openidc". For mod_auth_mellon use "mellon".
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}
The fully qualified host name the client is running on or responds to.
SSL/TLS port used to connect to client
Used to encrypt cookies, cache data, etc. If not supplied a random string will be generated.
Common root ancestor for all protected locations

mod_auth_oidc OIDC RP Client Options

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

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 (default: generated random string)

claim used when setting the REMOTE_USER variable (default: "sub")

mod_auth_mellon SP Client Options

certficate key file (default: None)
certficate file (default: None)
Used to form the MellonEndpointPath, e.g. {mellon_root}/{mellon_endpoint} (default: mellon)
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)
Add SAML OrganizationName to SP metadata (default: None)
Add SAML OrganizationDisplayName to SP metadata (default: None)
Add SAML OrganizationURL to SP metadata (default: None)
Web location to be protected by client. May be specified multiple times (default: [])

DEPRECATED OPTIONS

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.

Use -l or --protected-locations instead.

Use --client-hostname instead.

Use --client-https-port instead.

Use --location-root instead.

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>