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 --app-name APP_NAME -s | --keycloak-
12 server-url KEYCLOAK_SERVER_URL -r | --keycloak-realm KEYCLOAK_REALM -l
13 | --protected-locations PROTECTED_LOCATIONS [ options ]
14 Configure mod_auth_mellon or mod_auth_openidc as Keycloak client
17
20 -h, --help
21 show this help message and exit
22 --version
24 display version and exit
25 --no-root-check
27 permit running by non-root (default: False)
28 -v, --verbose
30 be chatty (default: False)
31 -d, --debug
33 turn on debug info (default: False)
34 --show-traceback
36 exceptions print traceback in addition to error message
37 (default: False)
38 --log-file LOG_FILE
40 log file pathname (default: /var/log/python-key‐
41 cloak-httpd-client/keycloak-httpd-client-install.log)
42 --app-name APP_NAME
44 name of the web app being protected by mod_auth_mellon (default:
45 None)
46 --force
48 forcefully override safety checks (default: False)
49 --permit-insecure-transport
51 Normally secure transport such as TLS is required, defeat this
52 check (default: False)
53 --tls-verify
55 TLS certificate verification for requests to the server. May be
56 one of case insenstive [true, yes, on] to enable, [false, no,
57 off] to disable. Or the pathname to a OpenSSL CA bundle to use.
58 (default: True)
59 Program Configuration:
62 --template-dir TEMPLATE_DIR
65 Template location (default: /usr/share/key‐
66 cloak-httpd-client/templates)
67 --httpd-dir HTTPD_DIR
69 Template location (default: /etc/httpd)
70 Keycloak IdP:
73 -r, --keycloak-realm KEYCLOAK_REALM
76 realm name (default: None)
77 -s, --keycloak-server-url KEYCLOAK_SERVER_URL
79 Keycloak server URL (default: None)
80 -a, --keycloak-auth-role root-admin|realm-admin|anonymous
82 authenticating as what type of user (default: root-admin)
83 -u, --keycloak-admin-username KEYCLOAK_ADMIN_USERNAME
85 admin user name (default: admin)
86 -P, --keycloak-admin-password-file KEYCLOAK_ADMIN_PASSWORD_FILE
88 file containing the admin password (or use a hyphen "-" to indi‐
89 cate the password will be read from stdin) (default: None)
90 --keycloak-admin-realm KEYCLOAK_ADMIN_REALM
92 realm admin belongs to (default: master)
93 --initial-access-token INITIAL_ACCESS_TOKEN
95 realm initial access token for client registeration (default:
96 None)
97 --client-originate-method native|registration
99 The method used on the Keycloak REST interface for creating a
100 new client. There are two possibilities.
101 native
102 A Keycloak clientRespresentation JSON object is sent to
103 the Keycloak client REST endpoint. This is a native Key‐
104 cloak data format understood only by Keycloak and as such
105 permits setting values unique to Keycloak. This is some‐
106 times refered to as the default client data format.
107 registration
108 The data used to create the client is sent to the Key‐
109 cloak registraton endpoint. The data format depends on
110 the type of client being created and can be contolled by
111 the --client-data-format. The registration method has the
112 advantage of not requiring admin privileges, see the
113 Authentication Levels and Permissions and 0 details.
114 (default: native)
115 --client-data-format CLIENT_DATA_FORMAT
117 Must be one of default|oidc|saml2. When using the registration
118 client originate method this selects the type of data used to
119 create the client. For OIDC it can be either default to use
120 Keycloak's clientRespresentation JSON object or oidc for the
121 OpenID Connect Dynamic Client Registration JSON object. For OIDC
122 it defaults to default For SAML it must be saml2.) (default:
123 default)
124 default
125 A Keycloak clientRepresentation JSON Object sent to the
126 /realms/{realm}/clients-registrations/default endpoint.
127 oidc
128 A OIDC Dynamic Client Registeration JSON object sent to
129 the /realms/{realm}/clients-registrations/openid-connect
130 endpoint
131 saml2
132 A SAML metadata entity descriptor in XML format sent to
133 the /realms/{realm}/clients-registrations/saml2-entity-
134 descriptor endpoint.
135 Common Client Options
138 -t, --client-type openidc|mellon
141 Which kind of client. For mod_auth_openidc use "openidc". For
142 mod_auth_mellon use "mellon".
143 --clientid CLIENTID
145 The clientid Keycloak identifies the client by. This has differ‐
146 ent meanings depending on the type of client.
147 SAML
148 It is the EntityID and defaults to
149 {client_https_url}/{mellon_root}/{mellon_end‐
150 point_path}/metadata)
151 OIDC
152 It is the clientid and defaults to {client_host‐
153 name}-{app_name}
154 --client-hostname CLIENT_HOSTNAME
156 The fully qualified host name the client is running on or
157 responds to.
158 --client-https-port CLIENT_HTTPS_PORT
160 SSL/TLS port used to connect to client
161 --crypto-passphrase CRYPTO_PASSPHRASE
163 Used to encrypt cookies, cache data, etc. If not supplied a
164 random string will be generated.
165 --location-root LOCATION_ROOT
167 Common root ancestor for all protected locations
168 mod_auth_oidc OIDC RP Client Options
171 --oidc-redirect-uri OIDC_REDIRECT_URI
174 The OIDC redirect_uri. Must be an antecedent (i.e. child) of one
175 of the protected locations. (default: The first protected loca‐
176 tion appened with "/redirect_uri")
177 --oidc-logout-uri OIDC_REDIRECT_URI
180 Can be used to add the location the user is redirected to after
181 logout as an additional redirectUri value in Keycloak's client
182 representation. The location should not be nested under any of
183 the protected locations, otherwise the login process would start
184 again. (default: None)
185 --oidc-client-secret OIDC_CLIENT_SECRET
188 OIDC client secret (default: generated random string)
189 --oidc-remote-user-claim OIDC_REMOTE_USER_CLAIM
192 claim used when setting the REMOTE_USER variable (default:
193 "sub")
194 mod_auth_mellon SP Client Options
199 --mellon-key-file MELLON_KEY_FILE
202 certficate key file (default: None)
203 --mellon-cert-file MELLON_CERT_FILE
205 certficate file (default: None)
206 --mellon-endpoint MELLON_ENDPOINT
208 Used to form the MellonEndpointPath, e.g. {mellon_root}/{mel‐
209 lon_endpoint} (default: mellon)
210 --mellon-idp-attr-name MELLON_IDP_ATTR_NAME
212 Name of the attribute mod_auth_mellon adds which will contain
213 the IdP entity id (default: {client_https_url}/{mel‐
214 lon_root}/{mellon_endpoint_path}/metadata)
215 --mellon-organization-name MELLON_ORGANIZATION_NAME
217 Add SAML OrganizationName to SP metadata (default: None)
218 --mellon-organization-display-name MELLON_ORGANIZATION_DISPLAY_NAME
220 Add SAML OrganizationDisplayName to SP metadata (default: None)
221 --mellon-organization-url MELLON_ORGANIZATION_URL
223 Add SAML OrganizationURL to SP metadata (default: None)
224 -l, --protected-locations PROTECTED_LOCATIONS
226 Web location to be protected by client. May be specified multi‐
227 ple times (default: [])
228
231 -p, --keycloak-admin-password
232 It is insecure to pass a password on the command line. Use one
233 of the other methods detailed in the How to pass the Keycloak
234 admin password topic.
235 --mellon-protected-locations
238 Use -l or --protected-locations instead.
239 --mellon-hostname
242 Use --client-hostname instead.
243 --mellon-https-port
246 Use --client-https-port instead.
247 --mellon-root
250 Use --location-root instead.
251 --mellon-entity-id
254 Use --clientid instead.
255
259 keycloak-httpd-client-install is used to configure a httpd (Apache)
260 instance using mod_auth_openidc or mod_auth_mellon authentication mod‐
261 ules as a client of the Keycloak Identity Provider (IdP) in order to
262 provide authentication and authorization services to web applications.
263 Quick Start
266 Despite the wealth of options this tool provides it can be run simply
268 needing a minimum of just 4 pieces of information:
269 * An application name
272 * A web resource to protect (e.g. location)
274 * The Keycloak server and realm
276 * Keycloak authentication credentials
278 Simple Example
281 sudo keycloak-httpd-client-install \
282 --app-name foo \
283 --protected-location /private \
284 --keycloak-server-url keycloak.example.com \
285 --keycloak-realm my_organization \
286 --keycloak-admin-password-file admin_passwd
287 Note, by default mod_auth_openidc will be configured as the client. To
289 configure mod_auth_mellon instead add this option: --client-type mel‐
290 lon.
291 How to pass the Keycloak admin password
293 The Keycloak admin password may be passed via one of the possible ways
296 listed here in the order the tool looks for the password.
297 1. Try the --keycloak-admin-password-file argument. If it's a hyphen
300 read the password from stdin, otherwise treat the argument as the name
301 of a file, open the file and read the password from the file.
302 2. Test for the existence of the KEYCLOAK_ADMIN_PASSWORD environment
305 variable. If the KEYCLOAK_ADMIN_PASSWORD is defined read the password
306 from it.
307 4. Prompt for the password from the terminal.
310 Authentication Levels and Permissions
313 The tool is capable of range of configuration steps. But the extent of
316 those operations may be circumscribed by the privilege level (autho‐
317 rization) the tool is run with. The privilege level is determined by
318 the --keycloak-auth-role command line option which may be one of:
319 root-admin: The Keycloak installation has a super realm normally called
322 master which is the container for all realms hosted by the Keycloak
323 instance. A user with administration priviliges in the master realm can
324 perform all operations on all realms hosted by the instance. Think of
325 such a user as a root user or root admin.
326 realm-admin: Each subordinate realm in the Keycloak instance may have
328 it's own administrator(s) whose privileges are restricted exclusively
329 to that realm.
330 anonymous: The tool does not authenticate as a user and hence no priv‐
332 iliges are granted. Any privilege is granted by virtue of an initial
333 access token passed in via the -initial-access-token command line
334 option. Think of an initial access token as a one time password scoped
335 to a specific realm. The initial access token must be generated by an
336 administrator with sufficient priviliges on the realm and given to the
337 user of the tool. The priviliges conferred by the initial access token
338 are limited to registering the client in the realm utilizing the Key‐
339 cloak client registration service.
340 Selecting which authencation role will be used is determined by a com‐
342 bination of the --keycloak-auth-role option and the --key‐
343 cloak-admin-realm option. When the authentication role is one of
344 root-admin or realm-admin the tool will authenticate as a user in a
345 specific realm, the --keycloak-admin-realm option declares the realm
346 the administrator will authenticate to. For the root-admin role this is
347 typically the master realm. For the realm-admin role this would be
348 realm the tool is registrating the client in.
349 Determining which authentication role to use
352 In general the principle of least privilige should apply. Grant to the
354 tool the least privilige necessary to perform the required action. In
355 oder of least privilige to greatest privilige the following operations
356 are possible under the defined authentication roles:
357 anonymous
360 * Can register the client using only the Keycloak client regis‐
362 tration service. The tool cannot determine a prori if the client
363 already exists in the realm nor can it adjust any configuration
364 options on the client.
365 * The realm must pre-exist.
367 realm-admin
369 * Can enumerate the existing clients in the realm to determine
371 if a conflict would occur.
372 * Can delete a pre-existing client and replace it with the new
374 client definition if the --force option is supplied.
375 * Can modify the clients configuration.
377 * Can use either the client registration service or the REST API
379 to create the client.
380 * The realm must pre-exist and contain the realm admin user.
382 root-admin
384 * Includes all of the priviliged operation conferred by the
386 realm-admin.
387 * Can enumerate existing realms on the Keycloak instance to ver‐
389 ify the existence of the target realm the client is to be
390 installed in.
391 * Can create the target realm if it does not exist.
393 Client creation methods
395 Keycloak offers two methods to add a client to a realm Selected with
397 --client-originate-method option.
398 registration
400 Originally designed to support the OIDC Dynmaic Client Registra‐
401 tion service it can also be used to register clients with Key‐
402 cloak's default clientRepresentation JSON Object or SAML SP
403 clients using SAML Entity Descriptor Metadata in XML format
404 depending on the exact endpoint utilized. See --cient-data-formt
405 for details. The primary benefit of the client origination
406 method is not requiring admin privileges, rather an initial
407 access token issued by the realm admin is used, this is called
408 anonymous authentication. Selected with --client-origi‐
409 nate-method register.
410 The client registration service requies the use of an initial
412 access token. For all authentiction roles an initial access
413 token can be provided on the command line via the ini‐
414 tial-access-token option. The initial access token will have to
415 have been provided by a Keycloak administrator who pre-creates
416 it. If the authencation role is either root-admin or realm-admin
417 the tool has sufficient privilige to obtain an initial access
418 token on it's behalf negating the need for a Keycloak admin to
419 supply one externally.
420 native
421 This method sends Keycloak's native clientRepresentation JSON
422 object to the auth/admin/realms/{realm}/clients client endpoint
423 to create or update a client.
424 If the client is a SAML SP it's Entity Descriptor XML Metadata
426 is first sent to the auth/admin/realms/{realm}/client-descrip‐
427 tion-converter conversion endpoint which returns a native clien‐
428 tRepresention JSON object derived from the SAML SP metadata. The
429 derived clientRepresentation is subsequently sent to the client
430 REST endpoint.
431 The client registration service may be used by the following authenti‐
433 cation roles:
434 * root-admin
436 * realm-admin
438 * anonymous (requires use of --initial-access-token)
440 The REST API may be used by the following authentication roles:
442 * root-admin
444 * realm-admin
446
449 keycloak-httpd-client-install performs the following operational steps
450 which can be grouped into two major operational groups:
451 * Configure the httpd client
453 * Add the httpd client to the Keycloak server.
455 Configure the httpd client
457 * Create directories.
459 Files written by keycloak-httpd-client-install need a destina‐
461 tion directory (see FILES). If the necessary directories are not
462 present they are created.
463 * Set up template environment
465 Many of the files written by keycloak-httpd-client-install are
467 based on jinga2 templates. The default template file location
468 can be overridden with the --template-dir option.
469 * Set up X509 Certificiates.
471 Some client configurations require the use of X509 certificates
473 and keys. If these were not supplied as an option a self-signed
474 certificate will be generated.
475 * Build the mod_auth_openidc or mod_auth_mellon httpd config file.
477 This is the httpd configuration file which will be installed in
479 Apache's conf.d configuration directory. It contains configura‐
480 tion directives for mod_auth_openidc or mod_auth_mellon depend‐
481 ing on which client is being configured.
482 * Build the client's protocol description
484 For mod_auth_openidc this means building JSON object which
486 describes the client. It will be sent to the Keycloak server to
487 add the client to the realm. For mod_auth_mellon this means
488 building the SAML SP XML metadata. The SP metadata is used both
489 by mod_auth_mellon when it initializes and is also sent to the
490 Keycloak server when adding the client to the Keycloak realm.
491 Add the httpd client to the Keycloak server.
493 * Connect to Keycloak Server.
495 A session is established with the Keycloak server. OAuth2 is
497 used to log in as the admin user using the --key‐
498 cloak-admin-username and --keycloak-admin-password-file options
499 if you're using admin privileges. Otherwise a non-authenticated
500 (e.g. anonymous) session is established and an initial access
501 token supplied to you by a Keycloak admin will be used to regis‐
502 ter the client.
503 * Query realms from Keycloak server, optionally create new realm.
505 Keycloak supports multi-tenancy, it may present many IdP's each
507 one specified by a Keycloak realm. The --keycloak-realm option
508 identifies which Keycloak realm we will bind to. The Keycloak
509 realm may already exist on the Keycloak server, if it does key‐
510 cloak-httpd-client-install will use it. If the Keycloak realm
511 does not exist yet it will be created for you.
512 Requires the root-admin auth role.
514 * Query realm clients from Keycloak server, optionally delete existing.
516 Before a new client can be added to the Keycloak realm we must
518 assure it does not conflict with an existing client. If the
519 client is already registered in the Keycloak realm key‐
520 cloak-httpd-client-install will stop processing and exit with an
521 error unless the --force option is used. --force will cause the
522 existing client on the Keycloak realm to be deleted first so
523 that it can be replaced in the next step.
524 Requires either the root-admin or realm-admin auth role.
526 * Create new client in Keycloak realm.
528 The client description is sent to one of the Keycloak server's
530 REST endpoints to add the client to the realm. The choice of
531 which endpoint is used and the data format sent is a function of
532 the client-originate-method, the auth role and client data for‐
533 mat. Most users will simply allow the tool to select the optimal
534 combination.
535 * Adjust client configuration
537 Override default Keycloak client values. This varies by Keycloak
539 release.
540 Requires either the root-admin or realm-admin auth role.
542 * Add attributes to be returned in assertion
544 The client is configured to return necessary attributes. The
546 added attributes are:
547 * Groups user is a member of.
549 Requires either the root-admin or realm-admin auth role.
551 * Retrieve IdP metadata from Keycloak server.
553 The mod_auth_mellon SP needs SAML metadata that describes the
555 Keycloak IdP. The metadata for the Keycloak IdP is fetched from
556 the Keycloak server and stored in a location referenced in the
557 mod_auth_mellon SP httpd configuration file. (see FILES)
558 mod_auth_openidc also needs a description of the Keycloak IdP
559 but unlike mod_auth_mellon it is capable of fetching the Key‐
560 cloak IdP description automatically via the OIDCProviderMeta‐
561 dataURL directive and periodically refreshing it. Therefore this
562 step is skipped for mod_auth_openidc.
563 STRUCTURE
566 The overarching organization is to produce a web application. An inde‐
568 pendent set of mod_auth_openidc or mod_auth_mellon files are created
569 per application and registered with the Keycloak server. This permits
570 multiple indpendent client and/or protected web resources to be handled
571 by one Apache instance. When you run keycloak-httpd-client-install you
572 must supply an application name via the --app-name option.
573 Within the web application you may protect multiple independent web
575 resources specified via the --protected-locations /xxx option. This
576 will cause a location block similar to this to be generated per loca‐
577 tion (depending on the client type):
578 mod_auth_openidc
580 OIDCClientID ...
581 OIDCProviderMetadataURL ...
582 OIDCCryptoPassphrase ...
583 OIDCClientSecret ...
584 OIDCRedirectURI ...
585 OIDCRemoteUserClaim ...
586 <Location /xxx>
588 AuthType openid-connect
589 Require valid-user
590 </Location>
591 mod_auth_mellon
592 <Location />
593 MellonEnable info
594 MellonEndpointPath ...
595 MellonSPMetadataFile ...
596 MellonSPPrivateKeyFile ...
597 MellonSPCertFile ...
598 MellonIdPMetadataFile ...
599 MellonIdP ...
600 </Location>
601 <Location /xxx>
603 AuthType Mellon
604 MellonEnable auth
605 Require valid-user
606 </Location>
607 These will be added to the client's HTTPD configuration file.
609 The location of the client configuration directives in the client con‐
611 figuration file depend on the client type.
612 For mod_auth_openidc the directives are global to the module and hence
614 can be located anywhere outside a location directive. The tool places
615 them at the top of the client configuration file.
616 For mod_auth_mellon the directives must be located in a location block
618 handled by mod_auth_mellon. mod_auth_mellon supports directive inheri‐
619 tance, thus any mod_auth_mellon location block located below in the URL
620 hierarchy will inherit directives from above. To avoid duplicate decla‐
621 rations of mod_auth_mellon directives that can be shared by subsequent
622 mod_auth_mellon location block (and protect against future cut-n-paste
623 errors) the shared common mod_auth_mellon directives are located at the
624 location-root.
625 Changes from the previous version
627 keycloak-httpd-client-install now supports mod_auth_opendic in addition
629 to mod_auth_mellon.
630 Some mod_auth_mellon specific options (e.g. --mellon-*) can be shared
632 with mod_auth_openidc. These were renamed to have a --client-* prefix
633 instead. The previous names continue to work but will emit a deprecaton
634 warning and will be removed in a future release.
635 The --client-originate descriptor method has been renamed to native.
637 The {httpd_dir}/saml2 directory containing SAML data files (e.g. meta‐
639 data, keys, certs, etc.) has been renamed to {httpd_dir}/federation to
640 better reflect it's use as a location to store data used in federated
641 authentication.
642
645 Directories and files created by running keycloak-httpd-client-install:
646 {httpd_dir}/federation
649 This directory contains data files used during federated authen‐
650 tication.
651 {httpd_dir}/conf.d/{app_name}_mellon_keycloak_{realm}.conf
654 This is the primary mod_auth_mellon configuration file for the
655 application. It binds to the Keycloak realm IdP. It is generated
656 from the mellon_httpd.conf template file.
657 {httpd_dir}/federation/{app_name}.cert
660 The mod_auth_mellon SP X509 certficate file in PEM format.
661 {httpd_dir}/federation/{app_name}.key
664 The mod_auth_mellon SP X509 key file in PEM format.
665 {httpd_dir}/federation/{app_name}_keycloak_{realm}_idp_metadata.xml
668 The Keycloak SAML2 IdP metadata file. It is fetched from the
669 Keycloak server.
670 {httpd_dir}/federation/{app_name}_sp_metadata.xml
673 The mod_auth_mellon SAML2 SP metadata file. It is generated from
674 the sp_metadata.xml template file.
675 {httpd_dir}/conf.d/{app_name}_oidc_keycloak_{realm}.conf
678 This is the primary mod_auth_openidc configuration file for the
679 application. It binds to the Keycloak realm IdP. It is generated
680 from the oidc_httpd.conf template file.
681 Files referenced by keycloak-httpd-client-install when it runs:
684 /usr/share/python-keycloak-httpd-client/templates/*
687 jinja2 templates
688 Log files:
691 /var/log/python-keycloak-httpd-client/keycloak-httpd-client-install.log
693 Installation log file
694 DEBUGGING
697 The --verbose and --debug options can be used to increase the level of
699 detail emitted on the console. However, note the log file logs every‐
700 thing at the DEBUG level so it is usually easier to consult the log
701 file when debugging (see LOGGING)
702 LOGGING
705 keycloak-httpd-client-install logs all it's operations to a rotated log
707 file. The default log file can be overridden with the --log-file
708 option. Each run of keycloak-httpd-client-install will create a new log
709 file. Any previous log file will be rotated as a numbered verson keep‐
710 ing a maximum of 3 previous log files. Logging to the log file occurs
711 at the DEBUG level that includes all HTTP requests and responses, this
712 is useful for debugging.
713 TEMPLATES
716 Many of the files generated by keycloak-httpd-client-install are pro‐
718 duced via jinja2 templates substituting values determined by key‐
719 cloak-httpd-client-install when it runs. The default template file
720 location can be overridden with the --template-dir option.
721 {template_dir}/mellon_httpd.conf The template used to generate the
724 httpd configuration file for mod_auth_mellon
725 {httpd_dir}/conf.d/{app_name}_mellon_keycloak_{realm}.conf
726 {template_dir}/sp_metadata.tpl The template used to generate SAML SP
729 Metadata.
730 {template_dir}/oidc_httpd.conf The template used to generate the httpd
733 configuration file for mod_auth_openidc
734 {httpd_dir}/conf.d/{app_name}_oidc_keycloak_{realm}.conf
735 {template_dir}/oidc-client-registration.tpl The template used to gener‐
738 ate the OIDC Dynamic Client Registration data sent to Keycloak's client
739 registration endpoint /realms/{realm}/clients-registrations/openid-con‐
740 nect.
741 {template_dir}/oidc-client-representation.tpl The template used to gen‐
744 erate the Keycloak clientRepresentation JSON object used to create a
745 new client using native method or the registration method using the
746 default client data format at the /realms/{realm}/clients-registra‐
747 tions/default endpoint.
748
751 0: SUCCESS
752 1: OPERATION_ERROR
754 2: CONFIGURATION_ERROR
756 3: INSUFFICIENT_PRIVILEGE
758 4: COMMUNICATION_ERROR
760 5: ALREADY_EXISTS_ERROR
762
765 John Dennis <jdennis@redhat.com>
766 keycloak-httpd-client-install(1)