1keycloak-httpd-client-installG(e1n)eral Commands Makneuyaclloak-httpd-client-install(1)
2
6 keycloak-httpd-client-install - Tools to configure Apache HTTPD as Key‐
7 cloak client
8
11 keycloak-httpd-client-install [-h] [--no-root-check] [-v] [-d]
12 [--show-traceback] [--log-file LOG_FILE] --app-name APP_NAME [--force]
13 [--permit-insecure-transport] [--tls-verify] [--template-dir TEM‐
14 PLATE_DIR] [--httpd-dir HTTPD_DIR] -r KEYCLOAK_REALM -s KEY‐
15 CLOAK_SERVER_URL [-a root-admin|realm-admin|anonymous] [-u KEY‐
16 CLOAK_ADMIN_USERNAME] -P KEYCLOAK_ADMIN_PASSWORD_FILE -p KEY‐
17 CLOAK_ADMIN_PASSWORD [--keycloak-admin-realm KEYCLOAK_ADMIN_REALM]
18 [--initial-access-token INITIAL_ACCESS_TOKEN] [--client-origi‐
19 nate-method descriptor|registration] [--mellon-key-file MEL‐
20 LON_KEY_FILE] [--mellon-cert-file MELLON_CERT_FILE] [--mellon-hostname
21 MELLON_HOSTNAME] [--mellon-https-port MELLON_HTTPS_PORT] [--mellon-root
22 MELLON_ROOT] [--mellon-endpoint MELLON_ENDPOINT] [--mellon-entity-id
23 MELLON_ENTITY_ID] [--mellon-idp-attr-name MELLON_IDP_ATTR_NAME] [--mel‐
24 lon-organization-name MELLON_ORGANIZATION_NAME] [--mellon-organiza‐
25 tion-display-name MELLON_ORGANIZATION_DISPLAY_NAME] [--mellon-organiza‐
26 tion-url MELLON_ORGANIZATION_URL] [-l MELLON_PROTECTED_LOCATIONS]
27 Configure mod_auth_mellon as Keycloak client
29
32 -h, --help
33 show this help message and exit
34 --no-root-check
36 permit running by non-root (default: False)
37 -v, --verbose
39 be chatty (default: False)
40 -d, --debug
42 turn on debug info (default: False)
43 --show-traceback
45 exceptions print traceback in addition to error message
46 (default: False)
47 --log-file LOG_FILE
49 log file pathname (default: /var/log/python-key‐
50 cloak-httpd-client/keycloak-httpd-client-install.log)
51 --app-name APP_NAME
53 name of the web app being protected by mellon (default: None)
54 --force
56 forcefully override safety checks (default: False)
57 --permit-insecure-transport
59 Normally secure transport such as TLS is required, defeat this
60 check (default: False)
61 --tls-verify
63 TLS certificate verification for requests to the server. May be
64 one of case insenstive [true, yes, on] to enable, [false, no,
65 off] to disable. Or the pathname to a OpenSSL CA bundle to use.
66 (default: True)
67 Program Configuration:
70 --template-dir TEMPLATE_DIR
73 Template location (default: /usr/share/key‐
74 cloak-httpd-client/templates)
75 --httpd-dir HTTPD_DIR
77 Template location (default: /etc/httpd)
78 Keycloak IdP:
81 -r, --keycloak-realm KEYCLOAK_REALM
84 realm name (default: None)
85 -s, --keycloak-server-url KEYCLOAK_SERVER_URL
87 Keycloak server URL (default: None)
88 -a, --keycloak-auth-role root-admin|realm-admin|anonymous
90 authenticating as what type of user (default: root-admin)
91 -u, --keycloak-admin-username KEYCLOAK_ADMIN_USERNAME
93 admin user name (default: admin)
94 -P, --keycloak-admin-password-file KEYCLOAK_ADMIN_PASSWORD_FILE
96 file containing the admin password (or use a hyphen "-" to indi‐
97 cate the password will be read from stdin) (default: None)
98 -p, --keycloak-admin-password KEYCLOAK_ADMIN_PASSWORD
100 admin password (or use a hyphen "-" to to indicate the password
101 will read from stdin) (default: None)
102 Deprecated. It is insecure to pass a password on the command
103 line. Use --keycloak-admin-password-file instead. It is no
104 longer possible to use this argument to pass a password. During
105 a transition period this argument will continue to accept a
106 hyphen to indicate the password should be read from stdin in a
107 manner identical to --keycloak-admin-password-file.
108 --keycloak-admin-realm KEYCLOAK_ADMIN_REALM
110 realm admin belongs to (default: master)
111 --initial-access-token INITIAL_ACCESS_TOKEN
113 realm initial access token for client registeration (default:
114 None)
115 --client-originate-method descriptor|registration
117 select Keycloak method for creating SAML client (default:
118 descriptor)
119 Mellon SP:
122 --mellon-key-file MELLON_KEY_FILE
125 certficate key file (default: None)
126 --mellon-cert-file MELLON_CERT_FILE
128 certficate file (default: None)
129 --mellon-hostname MELLON_HOSTNAME
131 Machine's fully qualified host name
132 --mellon-https-port MELLON_HTTPS_PORT
134 SSL/TLS port on mellon-hostname
135 --mellon-root MELLON_ROOT
137 Common root ancestor for all mellon endpoints
138 --mellon-endpoint MELLON_ENDPOINT
140 Used to form the MellonEndpointPath, e.g. {mellon_root}/{mel‐
141 lon_endpoint} (default: mellon)
142 --mellon-entity-id MELLON_ENTITY_ID
144 SP SAML Entity ID (default: {mellon_http_url}/{mel‐
145 lon_root}/{mellon_endpoint_path}/metadata)
146 --mellon-idp-attr-name MELLON_IDP_ATTR_NAME
148 Name of the attribute Mellon adds which will contain the IdP
149 entity id (default: {mellon_http_url}/{mellon_root}/{mellon_end‐
150 point_path}/metadata)
151 --mellon-organization-name MELLON_ORGANIZATION_NAME
153 Add SAML OrganizationName to SP metadata (default: None)
154 --mellon-organization-display-name MELLON_ORGANIZATION_DISPLAY_NAME
156 Add SAML OrganizationDisplayName to SP metadata (default: None)
157 --mellon-organization-url MELLON_ORGANIZATION_URL
159 Add SAML OrganizationURL to SP metadata (default: None)
160 -l, --mellon-protected-locations MELLON_PROTECTED_LOCATIONS
162 Web location to protect with Mellon. May be specified multiple
163 times (default: [])
164
167 keycloak-httpd-client-install will configure a node running Apache with
168 mod_auth_mellon as SAML Service Provider (SP) utilizing a Keycloak
169 server as an Identity Provider(IdP).
170 How to pass the Keycloak admin password
173 The Keycloak admin password may be passed via one of the possible ways
176 listed here in the order the tool looks for the password.
177 1. Try the --keycloak-admin-password-file argument. If it's a hyphen
180 read the password from stdin, otherwise treat the argument as the name
181 of a file, open the file and read the password from the file.
182 2. Test for the existence of the KEYCLOAK_ADMIN_PASSWORD environment
185 variable. If the KEYCLOAK_ADMIN_PASSWORD is defined read the password
186 from it.
187 3. Try the deprecated --keycloak-admin-password argument. If it's a
190 hyphen read the password from stdin, otherwise return an error because
191 passwords should never be passed on the command line.
192 4. Prompt for the password from the terminal.
195 Authentication Levels and Permissions
198 The tool is capable of range of configuration steps. But the extent of
201 those operations may be circumscribed by the privilege level (autho‐
202 rization) the tool is run with. The privilege level is determined by
203 the --keycloak-auth-role command line option which may be one of:
204 root-admin: The Keycloak installation has a super realm normally called
207 master which is the container for all realms hosted by the Keycloak
208 instance. A user with administration priviliges in the master realm can
209 perform all operations on all realms hosted by the instance. Think of
210 such a user as a root user or root admin.
211 realm-admin: Each subordinate realm in the Keycloak instance may have
213 it's own administrator(s) whose privileges are restricted exclusively
214 to that realm.
215 anonymous: The tool does not authenticate as a user and hence no priv‐
217 iliges are granted. Any privilege is granted by virtue of an initial
218 access token passed in via the -initial-access-token command line
219 option. Think of an initial access token as a one time password scoped
220 to a specific realm. The initial access token must be generated by an
221 administrator with sufficient priviliges on the realm and given to the
222 user of the tool. The priviliges conferred by the initial access token
223 are limited to registering the client in the realm utilizing the Key‐
224 cloak client registration service.
225 Selecting which authencation role will be used is determined by a com‐
227 bination of the --keycloak-auth-role option and the --key‐
228 cloak-admin-realm option. When the authentication role is one of
229 root-admin or realm-admin the tool will authenticate as a user in a
230 specific realm, the --keycloak-admin-realm option declares the realm
231 the administrator will authenticate to. For the root-admin role this is
232 typically the master realm. For the realm-admin role this would be
233 realm the tool is registrating the client in.
234 Determining which authentication role to use
237 In general the principle of least privilige should apply. Grant to the
239 tool the least privilige necessary to perform the required action. In
240 oder of least privilige to greatest privilige the following operations
241 are possible under the defined authentication roles:
242 anonymous
245 * Can register the client using only the Keycloak client regis‐
247 tration service. The tool cannot determine a prori if the client
248 already exists in the realm nor can it adjust any configuration
249 options on the client.
250 * The realm must pre-exist.
252 realm-admin
254 * Can enumerate the existing clients in the realm to determine
256 if a conflict would occur.
257 * Can delete a pre-existing client and replace it with the new
259 client definition if the --force option is supplied.
260 * Can modify the clients configuration.
262 * Can use either the client registration service or the REST API
264 to create the client.
265 * The realm must pre-exist and contain the realm admin user.
267 root-admin
269 * Includes all of the priviliged operation conferred by the
271 realm-admin.
272 * Can enumerate existing realms on the Keycloak instance to ver‐
274 ify the existence of the target realm the client is to be
275 installed in.
276 * Can create the target realm if it does not exist.
278 Client creation methods
281 Keycloak offers two methods to add a client to a realm
283 * The OpenID Connect client registration service. Note even
285 though we are registering a SAML Service Provider (SP) which is
286 not part of OAuth2 nor OpenID Connect the client registration
287 service is still capable of registering a SAML SP client.
288 Selected with --client-originate-method register.
289 * Utilizing the Keycloak REST API to create and configure the
291 SAML SP client. The Keycloak REST API utilizes a 2-step process
292 whereby the SP metadata is sent to the the Keycloak instance and
293 it returns a client descriptor which is then used to create the
294 client. Selected with --client-originate-method descriptor.
295 At the time of this writing the client registration service behaves
297 differently than the REST API. Advice on which to use is likely to be
298 dependent upone the Keycloak version. Note, if anonymous authentication
299 is used in conjunction with a initial access token then the client reg‐
300 istration service must be used.
301 The client registration service requies the use of an initial access
303 token. For all authentiction roles an initial access token can be pro‐
304 vided on the command line via the initial-access-token option. The ini‐
305 tial access token will have to have been provided by a Keycloak admin‐
306 istrator who pre-creates it. If the authencation role is either
307 root-admin or realm-admin the tool has sufficient privilige to obtain
308 an initial access token on it's behalf negating the need for a Keycloak
309 admin to supply one externally.
310 The client registration service may be used by the following authenti‐
312 cation roles:
313 * root-admin
315 * realm-admin
317 * anonymous (requires use of --initial-access-token)
319 The REST API may be used by the following authentication roles:
321 * root-admin
323 * realm-admin
325
328 keycloak-httpd-client-install performs the following operational steps:
329 * Connect to Keycloak Server.
332 A session is established with the Keycloak server. OAuth2 is
334 used to log in as the admin user using the --key‐
335 cloak-admin-username and --keycloak-admin-password-file options.
336 The Keycloak server is identified by the -keycloak-server-url
337 option. This step is performed first to assure the remaining
338 steps can complete successfully. A session is maintained for
339 efficiency reasons. You may also need to specify --key‐
340 cloak-admin-role and --keycloak-admin-realm to indicate the
341 privilege level you are authenticating with. An anonymous auth
342 role connects to the Keycloak service without any authentica‐
343 tion.
344 * Create directories.
347 Files written by keycloak-httpd-client-install need a destina‐
349 tion directory (see FILES). If the necessary directories are not
350 present they are created.
351 * Set up template environment
353 Many of the files written by keycloak-httpd-client-install are
355 based on jinga2 templates. The default template file location
356 can be overridden with the --template-dir option.
357 * Set up Service Provider X509 Certificiates.
359 A SAML SP must have a X509 certificate and key used to sign and
361 optionally encrypt it's SAML messages sent to the SAML IdP. key‐
362 cloak-httpd-client-install can generate a self-signed certifi‐
363 cate for you or you may supply your own key and certificate via
364 the --mellon-key-file and --mellon-cert-file options. The files
365 must be in PEM format.
366 * Build Mellon httpd config file.
368 The Mellon HTTPD configuration file tells mod_auth_mellon where
370 to find things such as certificates and metadata files as well
371 as what web resources to protect. It is generated from the mel‐
372 lon_httpd.conf template file. (see FILES). There is one mellon
373 httpd conf file per application.
374 * Build Mellon SP metadata file.
376 The Mellon SP needs to be registered with the Keycloak IdP. This
378 forms a trust relationship and provides infomation to the IdP
379 about the Mellon SP. Registering an SP with an IdP is done via a
380 SP metadata file. The Mellon SP metadata also instructs
381 mod_auth_mellon how to operate. The Mellon SP is generated from
382 the sp_metadata.tpl template file.
383 * Query realms from Keycloak server, optionally create new realm.
385 Keycloak supports multi-tenancy, it may serve many IdP's each
387 one specified by a Keycloak realm. The --keycloak-realm option
388 identifies which Keycloak realm we will bind to. The Keycloak
389 realm may already exist on the Keycloak server, if it does key‐
390 cloak-httpd-client-install will use it. If the Keycloak realm
391 does not exist yet it will be created for you.
392 Requires the root-admin auth role.
394 * Query realm clients from Keycloak server, optionally delete existing.
396 SAML SP's are one type of Keycloak client that can be serviced
398 by the Keycloak realm IdP. The Mellon SP is a new Keycloak
399 client which needs to be added to the Keycloak realm. However we
400 must assure the new client does not conflict with an existing
401 client on the Keycloak realm. If the Mellon SP is already regis‐
402 tered on the Keycloak realm keycloak-httpd-client-install will
403 stop processing and exit with an error unless the --force option
404 is used. --force will cause the existing client on the Keycloak
405 realm to be deleted first so that it can be replaced in the next
406 step.
407 Requires either the root-admin or realm-admin auth role.
409 * Create new SP client in Keycloak realm.
411 The Mellon SP is registered with the Keycloak realm on the Key‐
413 cloak server by sending the Keycloak server the Mellon SP meta‐
414 data to the Keycloak server.
415 When the client-originate-method is descriptor either the
417 root-admin or realm-admin auth role is required. When the
418 client-originate-method is registration the initial access token
419 is mandatory for the anonymous auth role and optional for the
420 root-admin or realm-admin roles.
421 * Adjust client configuration
424 Override default Keycloak client values. This varies by Keycloak
426 release.
427 Requires either the root-admin or realm-admin auth role.
429 * Add attributes to be returned in assertion
432 The client is configured to return necessary attributes. The
434 added attributes are:
435 * Groups user is a member of.
437 Requires either the root-admin or realm-admin auth role.
439 * Retrieve IdP metadata from Keycloak server.
442 The Mellon SP needs SAML metadata that describes the Keycloak
444 IdP. The metadata for the Keycloak IdP is fetched from the Key‐
445 cloak server and stored in a location referenced in the Mellon
446 SP httpd configuration file. (see FILES)
447 STRUCTURE
450 The overarching organization is the web application. An independent set
452 of Mellon files are created per application and registered with the
453 Keycloak server. This permits multiple indpendent SAML Service
454 Providers and/or protected web resources to be handled by one Apache
455 instance. When you run keycloak-httpd-client-install you must supply an
456 application name via the --app-name option.
457 Within the web application you may protect via SAML multiple indepen‐
459 dent web resources specified via the --mellon-protected-locations /xxx
460 option. This will cause a:
461 <Location>
463 AuthType Mellon
464 MellonEnable auth
465 Require valid-user
466 </Location>
467 directive to be added to the Mellon HTTPD configuration file. The Mel‐
470 lon SP parameters are located at the root of the web application root,
471 each protected location inherits from that.
472
475 Files created by running keycloak-httpd-client-install:
476 {httpd-dir}/conf.d/{app-name}_mellon_keycloak_{realm}.conf
478 This is the primary Mellon configuration file for the applica‐
479 tion. It binds to the Keycloak realm IdP. It is generated from
480 the mellon_httpd.conf template file.
481 {httpd-dir}/saml2/{app-name}.cert
484 The Mellon SP X509 certficate file in PEM format.
485 {httpd-dir}/saml2/{app-name}.key
488 The Mellon SP X509 key file in PEM format.
489 {httpd-dir}/saml2/{app-name}_keycloak_{realm}_idp_metadata.xml
492 The Keycloak SAML2 IdP metadata file. It is fetched from the
493 Keycloak server.
494 {httpd-dir}/saml2/{app-name}_sp_metadata.xml
497 The Mellon SAML2 SP metadata file. It is generated from the
498 sp_metadata.xml template file.
499 Files referenced by keycloak-httpd-client-install when it runs:
502 /usr/share/python-keycloak-httpd-client/templates/*
505 jinja2 templates
506 Log files:
509 /var/log/python-keycloak-httpd-client/keycloak-httpd-client-install.log
511 Installation log file
512 DEBUGGING
515 The --verbose and --debug options can be used to increase the level of
517 detail emitted on the console. However, note the log file logs every‐
518 thing at the DEBUG level so it is usually easier to consult the log
519 file when debugging (see LOGGING)
520 LOGGING
523 keycloak-httpd-client-install logs all it's operations to a rotated log
525 file. The default log file can be overridden with the --log-file
526 option. Each run of keycloak-httpd-client-install will create a new log
527 file. Any previous log file will be rotated as a numbered verson keep‐
528 ing a maximum of 3 previous log files. Logging to the log file occurs
529 at the DEBUG level that includes all HTTP requests and responses, this
530 is useful for debugging.
531 TEMPLATES
534 Many of the files generated by keycloak-httpd-client-install are pro‐
536 duced via jinja2 templates substituting values determined by key‐
537 cloak-httpd-client-install when it runs. The default template file
538 location can be overridden with the --template-dir option.
539
542 0: SUCCESS
543 1: OPERATION_ERROR
545 2: CONFIGURATION_ERROR
547 3: INSUFFICIENT_PRIVILEGE
549 4: COMMUNICATION_ERROR
551 5: ALREADY_EXISTS_ERROR
553
556 John Dennis <jdennis@redhat.com>
557 keycloak-httpd-client-install(1)