1keycloak-httpd-client-installG(e1n)eral Commands Makneuyaclloak-httpd-client-install(1)
2
3
4

NAME

6       keycloak-httpd-client-install - Tools to configure Apache HTTPD as Key‐
7       cloak client
8
9

SYNOPSIS

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
28       Configure mod_auth_mellon as Keycloak client
29
30

OPTIONS

32       -h, --help
33              show this help message and exit
34
35       --no-root-check
36              permit running by non-root (default: False)
37
38       -v, --verbose
39              be chatty (default: False)
40
41       -d, --debug
42              turn on debug info (default: False)
43
44       --show-traceback
45              exceptions   print   traceback  in  addition  to  error  message
46              (default: False)
47
48       --log-file LOG_FILE
49              log     file     pathname     (default:     /var/log/python-key‐
50              cloak-httpd-client/keycloak-httpd-client-install.log)
51
52       --app-name APP_NAME
53              name of the web app being protected by mellon (default: None)
54
55       --force
56              forcefully override safety checks (default: False)
57
58       --permit-insecure-transport
59              Normally  secure  transport such as TLS is required, defeat this
60              check (default: False)
61
62       --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
68
69       Program Configuration:
70
71
72       --template-dir TEMPLATE_DIR
73              Template        location        (default:        /usr/share/key‐
74              cloak-httpd-client/templates)
75
76       --httpd-dir HTTPD_DIR
77              Template location (default: /etc/httpd)
78
79
80       Keycloak IdP:
81
82
83       -r, --keycloak-realm KEYCLOAK_REALM
84              realm name (default: None)
85
86       -s, --keycloak-server-url KEYCLOAK_SERVER_URL
87              Keycloak server URL (default: None)
88
89       -a, --keycloak-auth-role root-admin|realm-admin|anonymous
90              authenticating as what type of user (default: root-admin)
91
92       -u, --keycloak-admin-username KEYCLOAK_ADMIN_USERNAME
93              admin user name (default: admin)
94
95       -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
99       -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
109       --keycloak-admin-realm KEYCLOAK_ADMIN_REALM
110              realm admin belongs to (default: master)
111
112       --initial-access-token INITIAL_ACCESS_TOKEN
113              realm  initial  access  token for client registeration (default:
114              None)
115
116       --client-originate-method descriptor|registration
117              select  Keycloak  method  for  creating  SAML  client  (default:
118              descriptor)
119
120
121       Mellon SP:
122
123
124       --mellon-key-file MELLON_KEY_FILE
125              certficate key file (default: None)
126
127       --mellon-cert-file MELLON_CERT_FILE
128              certficate file (default: None)
129
130       --mellon-hostname MELLON_HOSTNAME
131              Machine's fully qualified host name
132
133       --mellon-https-port MELLON_HTTPS_PORT
134              SSL/TLS port on mellon-hostname
135
136       --mellon-root MELLON_ROOT
137              Common root ancestor for all mellon endpoints
138
139       --mellon-endpoint MELLON_ENDPOINT
140              Used  to  form the MellonEndpointPath, e.g.  {mellon_root}/{mel‐
141              lon_endpoint} (default: mellon)
142
143       --mellon-entity-id MELLON_ENTITY_ID
144              SP   SAML   Entity    ID    (default:    {mellon_http_url}/{mel‐
145              lon_root}/{mellon_endpoint_path}/metadata)
146
147       --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
152       --mellon-organization-name MELLON_ORGANIZATION_NAME
153              Add SAML OrganizationName to SP metadata (default: None)
154
155       --mellon-organization-display-name MELLON_ORGANIZATION_DISPLAY_NAME
156              Add SAML OrganizationDisplayName to SP metadata (default: None)
157
158       --mellon-organization-url MELLON_ORGANIZATION_URL
159              Add SAML OrganizationURL to SP metadata (default: None)
160
161       -l, --mellon-protected-locations MELLON_PROTECTED_LOCATIONS
162              Web  location  to protect with Mellon. May be specified multiple
163              times (default: [])
164
165

DESCRIPTION

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
171
172       How to pass the Keycloak admin password
173
174
175       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
178
179       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
183
184       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
188
189       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
193
194       4. Prompt for the password from the terminal.
195
196
197       Authentication Levels and Permissions
198
199
200       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
205
206       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
212       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
216       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
226       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
235
236       Determining which authentication role to use
237
238       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
243
244       anonymous
245
246              * 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
251              * The realm must pre-exist.
252
253       realm-admin
254
255              *  Can  enumerate the existing clients in the realm to determine
256              if a conflict would occur.
257
258              * Can delete a pre-existing client and replace it with  the  new
259              client definition if the --force option is supplied.
260
261              * Can modify the clients configuration.
262
263              * Can use either the client registration service or the REST API
264              to create the client.
265
266              * The realm must pre-exist and contain the realm admin user.
267
268       root-admin
269
270              * Includes all of the  priviliged  operation  conferred  by  the
271              realm-admin.
272
273              * 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
277              * Can create the target realm if it does not exist.
278
279
280       Client creation methods
281
282       Keycloak offers two methods to add a client to a realm
283
284              *  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
290              *  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
296       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
302       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
311       The client registration service may be used by the following  authenti‐
312       cation roles:
313
314              * root-admin
315
316              * realm-admin
317
318              * anonymous (requires use of --initial-access-token)
319
320       The REST API may be used by the following authentication roles:
321
322              * root-admin
323
324              * realm-admin
325
326

OPERATION

328       keycloak-httpd-client-install performs the following operational steps:
329
330
331       * Connect to Keycloak Server.
332
333              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
345
346       * Create directories.
347
348              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
352       * Set up template environment
353
354              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
358       * Set up Service Provider X509 Certificiates.
359
360              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
367       * Build Mellon httpd config file.
368
369              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
375       * Build Mellon SP metadata file.
376
377              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
384       * Query realms from Keycloak server, optionally create new realm.
385
386              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
393              Requires the root-admin auth role.
394
395       * Query realm clients from Keycloak server, optionally delete existing.
396
397              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
408              Requires either the root-admin or realm-admin auth role.
409
410       * Create new SP client in Keycloak realm.
411
412              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
416              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
422
423       * Adjust client configuration
424
425              Override default Keycloak client values. This varies by Keycloak
426              release.
427
428              Requires either the root-admin or realm-admin auth role.
429
430
431       * Add attributes to be returned in assertion
432
433              The client is configured to  return  necessary  attributes.  The
434              added attributes are:
435
436                     * Groups user is a member of.
437
438              Requires either the root-admin or realm-admin auth role.
439
440
441       * Retrieve IdP metadata from Keycloak server.
442
443              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
448
449       STRUCTURE
450
451       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
458       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
462              <Location>
463                  AuthType Mellon
464                  MellonEnable auth
465                  Require valid-user
466              </Location>
467
468
469       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
473

FILES

475       Files created by running keycloak-httpd-client-install:
476
477       {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
482
483       {httpd-dir}/saml2/{app-name}.cert
484              The Mellon SP X509 certficate file in PEM format.
485
486
487       {httpd-dir}/saml2/{app-name}.key
488              The Mellon SP X509 key file in PEM format.
489
490
491       {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
495
496       {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
500
501       Files referenced by keycloak-httpd-client-install when it runs:
502
503
504       /usr/share/python-keycloak-httpd-client/templates/*
505              jinja2 templates
506
507
508       Log files:
509
510       /var/log/python-keycloak-httpd-client/keycloak-httpd-client-install.log
511              Installation log file
512
513
514       DEBUGGING
515
516       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
521
522       LOGGING
523
524       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
532
533       TEMPLATES
534
535       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
540

EXIT STATUS

542              0: SUCCESS
543
544              1: OPERATION_ERROR
545
546              2: CONFIGURATION_ERROR
547
548              3: INSUFFICIENT_PRIVILEGE
549
550              4: COMMUNICATION_ERROR
551
552              5: ALREADY_EXISTS_ERROR
553
554

AUTHOR

556       John Dennis <jdennis@redhat.com>
557
558
559
560                                              keycloak-httpd-client-install(1)
Impressum