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 [--key‐
17 cloak-admin-realm KEYCLOAK_ADMIN_REALM] [--initial-access-token INI‐
18 TIAL_ACCESS_TOKEN] [--client-originate-method descriptor|registration]
19 [--mellon-key-file MELLON_KEY_FILE] [--mellon-cert-file MEL‐
20 LON_CERT_FILE] [--mellon-hostname MELLON_HOSTNAME] [--mellon-https-port
21 MELLON_HTTPS_PORT] [--mellon-root MELLON_ROOT] [--mellon-endpoint MEL‐
22 LON_ENDPOINT] [--mellon-entity-id MELLON_ENTITY_ID] [--mel‐
23 lon-idp-attr-name MELLON_IDP_ATTR_NAME] [--mellon-organization-name
24 MELLON_ORGANIZATION_NAME] [--mellon-organization-display-name MEL‐
25 LON_ORGANIZATION_DISPLAY_NAME] [--mellon-organization-url MELLON_ORGA‐
26 NIZATION_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 KEYCLOAK_ADMIN_PASSWORD
96 admin password (use - to read from stdin) (default: None)
97 --keycloak-admin-realm KEYCLOAK_ADMIN_REALM
99 realm admin belongs to (default: master)
100 --initial-access-token INITIAL_ACCESS_TOKEN
102 realm initial access token for client registeration (default:
103 None)
104 --client-originate-method descriptor|registration
106 select Keycloak method for creating SAML client (default:
107 descriptor)
108 Mellon SP:
111 --mellon-key-file MELLON_KEY_FILE
114 certficate key file (default: None)
115 --mellon-cert-file MELLON_CERT_FILE
117 certficate file (default: None)
118 --mellon-hostname MELLON_HOSTNAME
120 Machine's fully qualified host name
121 --mellon-https-port MELLON_HTTPS_PORT
123 SSL/TLS port on mellon-hostname
124 --mellon-root MELLON_ROOT
126 Common root ancestor for all mellon endpoints
127 --mellon-endpoint MELLON_ENDPOINT
129 Used to form the MellonEndpointPath, e.g. {mellon_root}/{mel‐
130 lon_endpoint} (default: mellon)
131 --mellon-entity-id MELLON_ENTITY_ID
133 SP SAML Entity ID (default: {mellon_http_url}/{mel‐
134 lon_root}/{mellon_endpoint_path}/metadata)
135 --mellon-idp-attr-name MELLON_IDP_ATTR_NAME
137 Name of the attribute Mellon adds which will contain the IdP
138 entity id (default: {mellon_http_url}/{mellon_root}/{mellon_end‐
139 point_path}/metadata)
140 --mellon-organization-name MELLON_ORGANIZATION_NAME
142 Add SAML OrganizationName to SP metadata (default: None)
143 --mellon-organization-display-name MELLON_ORGANIZATION_DISPLAY_NAME
145 Add SAML OrganizationDisplayName to SP metadata (default: None)
146 --mellon-organization-url MELLON_ORGANIZATION_URL
148 Add SAML OrganizationURL to SP metadata (default: None)
149 -l, --mellon-protected-locations MELLON_PROTECTED_LOCATIONS
151 Web location to protect with Mellon. May be specified multiple
152 times (default: [])
153
156 keycloak-httpd-client-install will configure a node running Apache with
157 mod_auth_mellon as SAML Service Provider (SP) utilizing a Keycloak
158 server as an Identity Provider(IdP).
159 Authentication Levels and Permissions
162 The tool is capable of range of configuration steps. But the extent of
165 those operations may be circumscribed by the privilege level (autho‐
166 rization) the tool is run with. The privilege level is determined by
167 the --keycloak-auth-role command line option which may be one of:
168 root-admin: The Keycloak installation has a super realm normally called
171 master which is the container for all realms hosted by the Keycloak
172 instance. A user with administration priviliges in the master realm can
173 perform all operations on all realms hosted by the instance. Think of
174 such a user as a root user or root admin.
175 realm-admin: Each subordinate realm in the Keycloak instance may have
177 it's own administrator(s) whose privileges are restricted exclusively
178 to that realm.
179 anonymous: The tool does not authenticate as a user and hence no priv‐
181 iliges are granted. Any privilege is granted by virtue of an initial
182 access token passed in via the -initial-access-token command line
183 option. Think of an initial access token as a one time password scoped
184 to a specific realm. The initial access token must be generated by an
185 administrator with sufficient priviliges on the realm and given to the
186 user of the tool. The priviliges conferred by the initial access token
187 are limited to registering the client in the realm utilizing the Key‐
188 cloak client registration service.
189 Selecting which authencation role will be used is determined by a com‐
191 bination of the --keycloak-auth-role option and the --key‐
192 cloak-admin-realm option. When the authentication role is one of
193 root-admin or realm-admin the tool will authenticate as a user in a
194 specific realm, the --keycloak-admin-realm option declares the realm
195 the administrator will authenticate to. For the root-admin role this is
196 typically the master realm. For the realm-admin role this would be
197 realm the tool is registrating the client in.
198 Determining which authentication role to use
201 In general the principle of least privilige should apply. Grant to the
203 tool the least privilige necessary to perform the required action. In
204 oder of least privilige to greatest privilige the following operations
205 are possible under the defined authentication roles:
206 anonymous
209 * Can register the client using only the Keycloak client regis‐
211 tration service. The tool cannot determine a prori if the client
212 already exists in the realm nor can it adjust any configuration
213 options on the client.
214 * The realm must pre-exist.
216 realm-admin
218 * Can enumerate the existing clients in the realm to determine
220 if a conflict would occur.
221 * Can delete a pre-existing client and replace it with the new
223 client definition if the --force option is supplied.
224 * Can modify the clients configuration.
226 * Can use either the client registration service or the REST API
228 to create the client.
229 * The realm must pre-exist and contain the realm admin user.
231 root-admin
233 * Includes all of the priviliged operation conferred by the
235 realm-admin.
236 * Can enumerate existing realms on the Keycloak instance to ver‐
238 ify the existence of the target realm the client is to be
239 installed in.
240 * Can create the target realm if it does not exist.
242 Client creation methods
245 Keycloak offers two methods to add a client to a realm
247 * The OpenID Connect client registration service. Note even
249 though we are registering a SAML Service Provider (SP) which is
250 not part of OAuth2 nor OpenID Connect the client registration
251 service is still capable of registering a SAML SP client.
252 Selected with --client-originate-method register.
253 * Utilizing the Keycloak REST API to create and configure the
255 SAML SP client. The Keycloak REST API utilizes a 2-step process
256 whereby the SP metadata is sent to the the Keycloak instance and
257 it returns a client descriptor which is then used to create the
258 client. Selected with --client-originate-method descriptor.
259 At the time of this writing the client registration service behaves
261 differently than the REST API. Advice on which to use is likely to be
262 dependent upone the Keycloak version. Note, if anonymous authentication
263 is used in conjunction with a initial access token then the client reg‐
264 istration service must be used.
265 The client registration service requies the use of an initial access
267 token. For all authentiction roles an initial access token can be pro‐
268 vided on the command line via the initial-access-token option. The ini‐
269 tial access token will have to have been provided by a Keycloak admin‐
270 istrator who pre-creates it. If the authencation role is either
271 root-admin or realm-admin the tool has sufficient privilige to obtain
272 an initial access token on it's behalf negating the need for a Keycloak
273 admin to supply one externally.
274 The client registration service may be used by the following authenti‐
276 cation roles:
277 * root-admin
279 * realm-admin
281 * anonymous (requires use of --initial-access-token)
283 The REST API may be used by the following authentication roles:
285 * root-admin
287 * realm-admin
289
292 keycloak-httpd-client-install performs the following operational steps:
293 * Connect to Keycloak Server.
296 A session is established with the Keycloak server. OAuth2 is
298 used to log in as the admin user using the --key‐
299 cloak-admin-username and --keycloak-admin-password options. The
300 Keycloak server is identified by the -keycloak-server-url
301 option. This step is performed first to assure the remaining
302 steps can complete successfully. A session is maintained for
303 efficiency reasons. You may also need to specify --key‐
304 cloak-admin-role and --keycloak-admin-realm to indicate the
305 privilege level you are authenticating with. An anonymous auth
306 role connects to the Keycloak service without any authentica‐
307 tion.
308 * Create directories.
311 Files written by keycloak-httpd-client-install need a destina‐
313 tion directory (see FILES). If the necessary directories are not
314 present they are created.
315 * Set up template environment
317 Many of the files written by keycloak-httpd-client-install are
319 based on jinga2 templates. The default template file location
320 can be overridden with the --template-dir option.
321 * Set up Service Provider X509 Certificiates.
323 A SAML SP must have a X509 certificate and key used to sign and
325 optionally encrypt it's SAML messages sent to the SAML IdP. key‐
326 cloak-httpd-client-install can generate a self-signed certifi‐
327 cate for you or you may supply your own key and certificate via
328 the --mellon-key-file and --mellon-cert-file options. The files
329 must be in PEM format.
330 * Build Mellon httpd config file.
332 The Mellon HTTPD configuration file tells mod_auth_mellon where
334 to find things such as certificates and metadata files as well
335 as what web resources to protect. It is generated from the mel‐
336 lon_httpd.conf template file. (see FILES). There is one mellon
337 httpd conf file per application.
338 * Build Mellon SP metadata file.
340 The Mellon SP needs to be registered with the Keycloak IdP. This
342 forms a trust relationship and provides infomation to the IdP
343 about the Mellon SP. Registering an SP with an IdP is done via a
344 SP metadata file. The Mellon SP metadata also instructs
345 mod_auth_mellon how to operate. The Mellon SP is generated from
346 the sp_metadata.tpl template file.
347 * Query realms from Keycloak server, optionally create new realm.
349 Keycloak supports multi-tenancy, it may serve many IdP's each
351 one specified by a Keycloak realm. The --keycloak-realm option
352 identifies which Keycloak realm we will bind to. The Keycloak
353 realm may already exist on the Keycloak server, if it does key‐
354 cloak-httpd-client-install will use it. If the Keycloak realm
355 does not exist yet it will be created for you.
356 Requires the root-admin auth role.
358 * Query realm clients from Keycloak server, optionally delete existing.
360 SAML SP's are one type of Keycloak client that can be serviced
362 by the Keycloak realm IdP. The Mellon SP is a new Keycloak
363 client which needs to be added to the Keycloak realm. However we
364 must assure the new client does not conflict with an existing
365 client on the Keycloak realm. If the Mellon SP is already regis‐
366 tered on the Keycloak realm keycloak-httpd-client-install will
367 stop processing and exit with an error unless the --force option
368 is used. --force will cause the existing client on the Keycloak
369 realm to be deleted first so that it can be replaced in the next
370 step.
371 Requires either the root-admin or realm-admin auth role.
373 * Create new SP client in Keycloak realm.
375 The Mellon SP is registered with the Keycloak realm on the Key‐
377 cloak server by sending the Keycloak server the Mellon SP meta‐
378 data to the Keycloak server.
379 When the client-originate-method is descriptor either the
381 root-admin or realm-admin auth role is required. When the
382 client-originate-method is registration the initial access token
383 is mandatory for the anonymous auth role and optional for the
384 root-admin or realm-admin roles.
385 * Adjust client configuration
388 Override default Keycloak client values. This varies by Keycloak
390 release.
391 Requires either the root-admin or realm-admin auth role.
393 * Add attributes to be returned in assertion
396 The client is configured to return necessary attributes. The
398 added attributes are:
399 * Groups user is a member of.
401 Requires either the root-admin or realm-admin auth role.
403 * Retrieve IdP metadata from Keycloak server.
406 The Mellon SP needs SAML metadata that describes the Keycloak
408 IdP. The metadata for the Keycloak IdP is fetched from the Key‐
409 cloak server and stored in a location referenced in the Mellon
410 SP httpd configuration file. (see FILES)
411 STRUCTURE
414 The overarching organization is the web application. An independent set
416 of Mellon files are created per application and registered with the
417 Keycloak server. This permits multiple indpendent SAML Service
418 Providers and/or protected web resources to be handled by one Apache
419 instance. When you run keycloak-httpd-client-install you must supply an
420 application name via the --app-name option.
421 Within the web application you may protect via SAML multiple indepen‐
423 dent web resources specified via the --mellon-protected-locations /xxx
424 option. This will cause a:
425 <Location>
427 AuthType Mellon
428 MellonEnable auth
429 Require valid-user
430 </Location>
431 directive to be added to the Mellon HTTPD configuration file. The Mel‐
434 lon SP parameters are located at the root of the web application root,
435 each protected location inherits from that.
436
439 Files created by running keycloak-httpd-client-install:
440 {httpd-dir}/conf.d/{app-name}_mellon_keycloak_{realm}.conf
442 This is the primary Mellon configuration file for the applica‐
443 tion. It binds to the Keycloak realm IdP. It is generated from
444 the mellon_httpd.conf template file.
445 {httpd-dir}/saml2/{app-name}.cert
448 The Mellon SP X509 certficate file in PEM format.
449 {httpd-dir}/saml2/{app-name}.key
452 The Mellon SP X509 key file in PEM format.
453 {httpd-dir}/saml2/{app-name}_keycloak_{realm}_idp_metadata.xml
456 The Keycloak SAML2 IdP metadata file. It is fetched from the
457 Keycloak server.
458 {httpd-dir}/saml2/{app-name}_sp_metadata.xml
461 The Mellon SAML2 SP metadata file. It is generated from the
462 sp_metadata.xml template file.
463 Files referenced by keycloak-httpd-client-install when it runs:
466 /usr/share/python-keycloak-httpd-client/templates/*
469 jinja2 templates
470 Log files:
473 /var/log/python-keycloak-httpd-client/keycloak-httpd-client-install.log
475 Installation log file
476 DEBUGGING
479 The --verbose and --debug options can be used to increase the level of
481 detail emitted on the console. However, note the log file logs every‐
482 thing at the DEBUG level so it is usually easier to consult the log
483 file when debugging (see LOGGING)
484 LOGGING
487 keycloak-httpd-client-install logs all it's operations to a rotated log
489 file. The default log file can be overridden with the --log-file
490 option. Each run of keycloak-httpd-client-install will create a new log
491 file. Any previous log file will be rotated as a numbered verson keep‐
492 ing a maximum of 3 previous log files. Logging to the log file occurs
493 at the DEBUG level that includes all HTTP requests and responses, this
494 is useful for debugging.
495 TEMPLATES
498 Many of the files generated by keycloak-httpd-client-install are pro‐
500 duced via jinja2 templates substituting values determined by key‐
501 cloak-httpd-client-install when it runs. The default template file
502 location can be overridden with the --template-dir option.
503
506 0: SUCCESS
507 1: OPERATION_ERROR
509 2: CONFIGURATION_ERROR
511 3: INSUFFICIENT_PRIVILEGE
513 4: COMMUNICATION_ERROR
515 5: ALREADY_EXISTS_ERROR
517
520 John Dennis <jdennis@redhat.com>
521 keycloak-httpd-client-install(1)