httpd_configmap_generator 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: f02888b03610f25e11d9d82ef0b3d4e7f32d23dc
+  data.tar.gz: 715398b32432b9e0880df06bd5212f59614769bd
+SHA512:
+  metadata.gz: ecfd0afeede3a311f59c536cf5f72ff70b65e3f29f204034f03d733279bbfe0824abadf676d46d5a794b8a04e8bd24373037dfb46e8714a7f5c6ee30de2b940c
+  data.tar.gz: 73704e1d3a209c3b7d325b4cf683913d8c0b4db293d5c2e73f1fe78124306cafb31ff5ab31a954f342f95a97356731277ed560a3dd7fbfa68426ed68ae734f76

data/.gitignore

@@ -0,0 +1,11 @@
+.rubocop-*
+/bundle/
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/

data/.rspec

@@ -0,0 +1 @@
+--require spec_helper

data/.travis.yml

@@ -0,0 +1,14 @@
+language: ruby
+rvm:
+- '2.3.5'
+- '2.4.2'
+sudo: false
+cache: bundler
+after_script: bundle exec codeclimate-test-reporter
+notifications:
+  webhooks:
+    urls:
+    - https://webhooks.gitter.im/e/0357efbc3cba43430d2b
+    on_success: change
+    on_failure: always
+    on_start: never

data/Dockerfile

@@ -0,0 +1,16 @@
+FROM manageiq/httpd:latest
+MAINTAINER ManageIQ https://github.com/ManageIQ
+
+LABEL name="httpd-configmap-generator" \
+      summary="httpd image for configuring external authentication" \
+      description="An httpd image which can configure external authentication and generate the auth-config map" \
+      io.k8s.display-name="Httpd with Authentication Configuration" \
+      io.k8s.description="An httpd image which can configure external authentication and generate the auth-config map"
+
+ENV HTTPD_AUTH_TYPE=internal \
+    HTTPD_AUTH_KERBEROS_REALMS=undefined \
+    TERM=xterm
+
+RUN yum -y install openldap-clients pamtester
+
+RUN gem install --no-ri --no-rdoc --no-document httpd_configmap_generator

data/Gemfile

@@ -0,0 +1,4 @@
+source "https://rubygems.org"
+
+# Leverage the httpd_configmap_generator.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "{}"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright {yyyy} {name of copyright owner}
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

data/README-active-directory.md

@@ -0,0 +1,38 @@
+# Httpd Configmap Generator - Active Directory
+
+This documents how to run the httpd\_configmap\_generator tool to configure external authentication
+by joining an Active Directory domain.
+
+
+## Usage for the `active-directory` auth-type:
+
+```
+$ httpd_configmap_generator active-directory --help
+httpd_configmap_generator 0.1.0 - External Authentication Configuration script
+
+Usage: httpd_configmap_generator auth_type | update | export [--help | options]
+
+httpd_configmap_generator options are:
+  -V, --version              Version of the httpd_configmap_generator command
+  -h, --host=<s>             Application Domain (default: )
+  -o, --output=<s>           Configuration map file to create (default: )
+  -a, --ad-domain=<s>        Active Directory Domain (default: )
+  -u, --ad-server=<s>        Active Directory User (default: )
+  -p, --ad-password=<s>      Active Directory Password (default: )
+  -f, --force                Force configuration if configured already
+  -d, --debug                Enable debugging
+  -r, --ad-realm=<s>         Active Directory Realm (default: )
+  -e, --help                 Show this message
+```
+
+### Example:
+
+```
+$ httpd_configmap_generator active-directory \
+   --host=application.example.com  \
+   --ad-domain=example.com         \
+   --ad-realm=EXAMPLE.COM          \
+   --ad-user=Administrator         \
+   --ad-password=smartvm           \
+   -o /tmp/external-active-directory.yaml
+```

data/README-ipa.md

@@ -0,0 +1,41 @@
+# Httpd Configmap Generator - IPA
+
+This documents how to run the httpd\_configmap\_generator tool to configure external authentication
+for an IPA server.
+
+
+## Usage for the `ipa` auth-type:
+
+```
+$ httpd_configmap_generator ipa --help
+httpd_configmap_generator 0.1.0 - External Authentication Configuration script
+
+Usage: httpd_configmap_generator auth_type | update | export [--help | options]
+
+httpd_configmap_generator options are:
+  -V, --version              Version of the httpd_configmap_generator command
+  -h, --host=<s>             Application Domain (default: )
+  -o, --output=<s>           Configuration map file to create (default: )
+  -i, --ipa-server=<s>       IPA Server Fqdn (default: )
+  -p, --ipa-password=<s>     IPA Server Password (default: )
+  -f, --force                Force configuration if configured already
+  -d, --debug                Enable debugging
+  -a, --ipa-principal=<s>    IPA Server Principal (default: admin)
+  -m, --ipa-domain=<s>       Domain of IPA Server (default: )
+  -r, --ipa-realm=<s>        Realm of IPA Server (default: )
+  -e, --help                 Show this message
+```
+
+### Example:
+
+```
+$ httpd_configmap_generator ipa \
+   --force                                 \
+   --host=application.example.com          \
+   --ipa-server=ipaserver7.example.com     \
+   --ipa-domain=example.com                \
+   --ipa-realm=EXAMPLE.COM                 \
+   --ipa-principal=admin                   \
+   --ipa-password=smartvm                  \
+   -o /tmp/external-ipa.yaml
+```

data/README-saml.md

@@ -0,0 +1,70 @@
+# Httpd Configmap Generator - SAML
+
+This documents how to run the httpd\_configmap\_generator tool to configure the container against a SAML identity provider.
+
+## Usage for the `saml` auth-type:
+
+```
+$ httpd_configmap_generator saml --help
+httpd_configmap_generator 0.1.0 - External Authentication Configuration script
+
+Usage: httpd_configmap_generator auth_type | update | export [--help | options]
+
+httpd_configmap_generator options are:
+  -V, --version                  Version of the httpd_configmap_generator command
+  -h, --host=<s>                 Application Domain (default: )
+  -o, --output=<s>               Configuration map file to create (default: )
+  -f, --force                    Force configuration if configured already
+  -d, --debug                    Enable debugging
+  -k, --keycloak-add-metadata    Download and add the Keycloak metadata file
+  -e, --keycloak-server=<s>      Keycloak Server Fqdn or IP (default: )
+  -y, --keycloak-realm=<s>       Keycloak Realm for this client (default: )
+  -l, --help                     Show this message
+```
+
+### Examples:
+
+Creates the mellon metadata files and certificate for the container:
+
+```
+$ httpd_configmap_generator saml \
+    --force                                     \
+    --host=application.example.com              \
+    --debug                                     \
+    -o /tmp/external-saml.yaml
+```
+
+With the above, the IdP metadata file still needs to be fetched from the SAML Identity Provider and added to the configmap.
+
+For keycloak, this can be done with the following command:
+
+```
+$ httpd_configmap_generator update \
+    --input=/tmp/external-saml.yaml               \
+    --add-file=http://keycloak-server.example.com:8080/auth/realms/testrealm/protocol/saml/descriptor,/etc/httpd/saml2/idp-metadata.xml,644:root:root \
+    --output=/tmp/external-saml-keycloak.yaml
+```
+
+_Note_: If the Realm is already created on the Keycloak server, the following example initializes the mellon metadata files and certificates as well as downloads the IdP metadata file from Keycloak in a single command:
+
+```
+$ httpd_configmap_generator saml     \
+    --force                                         \
+    --host=application.example.com                  \
+    --keycloak-add-metadata                         \
+    --keycloak-server=keycloak-server.example.com   \
+    --keycloak-realm=testrealm                      \
+    --debug                                         \
+    -o /tmp/external-saml.yaml
+```
+
+In the above example, the auth configmap file would include the following files:
+
+* /etc/httpd/saml2/
+  - miqsp-metadata.xml
+  - miqsp-cert.cert
+  - miqsp-key.key
+  - idp-metadata.xml
+
+For Keycloak, the `miqsp-metadata.xml` file can be imported to create the Client ID for
+the `application.example.com` application domain.

data/README.md

@@ -0,0 +1,386 @@
+# Httpd Configmap Generator
+
+[![Gem Version](https://badge.fury.io/rb/httpd_configmap_generator.svg)](http://badge.fury.io/rb/httpd_configmap_generator)
+[![Build Status](https://travis-ci.org/ManageIQ/httpd_configmap_generator.svg)](https://travis-ci.org/ManageIQ/httpd_configmap_generator)
+[![Code Climate](https://codeclimate.com/github/ManageIQ/httpd_configmap_generator.svg)](https://codeclimate.com/github/ManageIQ/httpd_configmap_generator)
+[![Test Coverage](https://codeclimate.com/github/ManageIQ/httpd_configmap_generator/badges/coverage.svg)](https://codeclimate.com/github/ManageIQ/httpd_configmap_generator/coverage)
+[![Dependency Status](https://gemnasium.com/ManageIQ/httpd_configmap_generator.svg)](https://gemnasium.com/ManageIQ/httpd_configmap_generator)
+[![Security](https://hakiri.io/github/ManageIQ/httpd_configmap_generator/master.svg)](https://hakiri.io/github/ManageIQ/httpd_configmap_generator/master)
+
+[![Chat](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/ManageIQ/authentication?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
+
+This GEM provides a CLI to automate the generation of auth-config maps
+which can be used with the httpd auth pod for enabling external authentication.
+
+Install as follows:
+
+```
+gem install httpd_configmap_generator
+```
+
+## Running the tool
+
+Generating an auth-config map can be done by running the httpd\_configmap\_generator tool
+
+```
+$ httpd_configmap_generator
+
+Usage: httpd_configmap_generator auth_type | update | export [--help | options]
+Supported auth_type: active-directory, ipa, saml
+```
+
+Showing the usage for each authentication type or sub-command as follows:
+
+```
+$ httpd_configmap_generator ipa --help
+```
+
+## Supported Authentication Types
+
+|auth-type         | Identity Provider/Environment                  | for usage: |
+|------------------|------------------------------------------------|------------|
+| active-directory | Active Directory domain realm join             | [README-active-directory](README-active-directory.md) |
+| ipa              | IPA, IPA 2-factor authentication, IPA/AD Trust | [README-ipa](README-ipa.md) |
+| saml             | Keycloak, etc.                                 | [README-saml](README-saml.md) |
+
+___
+
+## Updating an auth configuration map:
+
+With the `update` subcommand, it is possible to add file(s) to the configuration
+map as per the following usage:
+
+
+```
+$ httpd_configmap_generator update --help
+httpd_configmap_generator 0.1.0 - External Authentication Configuration script
+
+Usage: httpd_configmap_generator auth_type | update | export [--help | options]
+
+httpd_configmap_generator options are:
+  -V, --version         Version of the httpd_configmap_generator command
+  -i, --input=<s>       Input config map file (default: )
+  -o, --output=<s>      Output config map file (default: )
+  -f, --force           Force configuration if configured already
+  -d, --debug           Enable debugging
+  -a, --add-file=<s>    Add file to config map (default: )
+  -h, --help            Show this message
+```
+
+The `--add-file` option can be specified multiple times, one per file to add
+to a configuration map.
+
+Supported file specification for the `--add-file` option are:
+
+```
+--add-file=file-path
+--add-file=source-file-path,target-file-path
+--add-file=source-file-path,target-file-path,file-permission
+--add-file=file-url,target-file-path,file-permission
+```
+
+Where:
+
+* file-url is an http URL
+* file-permission can be specified as: `mode:owner:group`
+
+Examples:
+
+### Adding files by specifying paths:
+
+The file ownership and permissions will be based on the files specified.
+
+```
+$ httpd_configmap_generator update \
+  --input=/tmp/original-auth-configmap.yaml                    \
+  --add-file=/etc/openldap/cacerts/primary-directory-cert.pem  \
+  --add-file=/etc/openldap/cacerts/seconday-directory-cert.pem \
+  --output=/tmp/updated-auth-configmap.yaml
+```
+
+### Adding target files from different source directories:
+
+
+```
+$ httpd_configmap_generator update \
+  --input=/tmp/original-auth-configmap.yaml                                        \
+  --add-file=/tmp/uploaded-cert1,/etc/openldap/cacerts/primary-directory-cert.pem  \
+  --add-file=/tmp/uploaded-cert2,/etc/openldap/cacerts/seconday-directory-cert.pem \
+  --output=/tmp/updated-auth-configmap.yaml
+```
+
+The file ownership and permissions will be based on the source files specified,
+in this case the ownership and permissiong of the `/tmp/uploaded-cert1`
+and `/tmp/uploaded-cert2` files will be used.
+
+### Adding a target file with user specified ownership and mode:
+
+```
+$ httpd_configmap_generator update \
+  --input=/tmp/original-auth-configmap.yaml                          \
+  --add-file=/tmp/secondary-keytab,/etc/http2.keytab,600:apache:root \
+  --output=/tmp/updated-auth-configmap.yaml
+```
+
+### Adding files by URL:
+
+```
+$ httpd_configmap_generator update \
+  --input=/tmp/original-auth-configmap.yaml \
+  --add-file=http://aab-keycloak:8080/auth/realms/miq/protocol/saml/description,/etc/httpd/saml2/idp-metadata.xml,644:root:root \
+  --output=/tmp/updated-auth-configmap.yaml
+```
+
+When downloading a file by URL, a target file path and file ownership/mode must be specified.
+
+___
+
+## Exporting a file from an auth configuration map
+
+With the `export` subcommand, it is possible to export a file from the configuration
+map as per the following usage:
+
+
+```
+$ httpd_configmap_generator export --help
+httpd_configmap_generator 0.1.0 - External Authentication Configuration script
+
+Usage: httpd_configmap_generator auth_type | update | export [--help | options]
+
+httpd_configmap_generator options are:
+  -V, --version       Version of the httpd_configmap_generator command
+  -i, --input=<s>     Input config map file (default: )
+  -l, --file=<s>      Config map file to export (default: )
+  -o, --output=<s>    The output file being exported (default: )
+  -f, --force         Force configuration if configured already
+  -d, --debug         Enable debugging
+  -h, --help          Show this message
+```
+
+Example:
+
+Extract the sssd.conf file out of the auth configuration map:
+
+```
+$ httpd_configmap_generator export \
+  --input=/tmp/external-ipa.yaml \
+  --file=/etc/sssd/sssd.conf     \
+  --output=/tmp/sssd.conf
+```
+
+# Building the Httpd Configmap Generator in a Container
+
+Container for configuring external authentication for the httpd auth pod.
+It is based on the auth httpd container and generates the httpd auth-config map
+needed to enable external authentication.
+
+## Installing
+
+```
+$ git clone https://github.com/ManageIQ/httpd_configmap_generator.git
+```
+
+___
+
+## Running with Docker
+
+### Building container image
+
+```
+$ cd httpd_configmap_generator
+$ docker build . -t manageiq/httpd_configmap_generator:latest
+```
+
+### Running the httpd\_configmap\_generator container
+
+
+```
+$ docker run --privileged manageiq/httpd_configmap_generator:latest &
+```
+
+Getting the httpd_configmap_generator container id:
+
+```
+$ CONFIGMAP_GENERATOR_ID="`docker ps -l -q`"
+```
+
+### Generating a configmap for external authentication against IPA
+
+While the httpd_configmap_generator tool can be run in the container by first getting into a bash shell:
+
+```
+$ docker exec -it $CONFIGMAP_GENERATOR_ID /bin/bash -i
+```
+
+The tool can also be executed directly as follows:
+
+Example for generating a configuration map for IPA:
+
+```
+$ docker exec $CONFIGMAP_GENERATOR_ID httpd_configmap_generator ipa \
+    --host=miq-appliance.example.com    \
+    --ipa-server=ipaserver.example.com  \
+    --ipa-domain=example.com            \
+    --ipa-realm=EXAMPLE.COM             \
+    --ipa-principal=admin               \
+    --ipa-password=smartvm1             \
+    -o /tmp/external-ipa.yaml
+```
+
+`--host` above must be the DNS of the application exposing the httpd auth pod,
+
+i.e. ${APPLICATION_DOMAIN}
+
+
+Copying the new auth configmap back locally:
+
+```
+$ docker cp $CONFIGMAP_GENERATOR_ID:/tmp/external-ipa.yaml ./external-ipa.yaml
+```
+
+The new configmap can then be applied to the auth httpd pod and then redeployed to take effect:
+
+```
+$ oc replace configmaps httpd-auth-configs --filename ./external-ipa.yaml
+```
+
+#### Stopping the httpd\_configmap\_generator container
+
+When completed with httpd\_configmap\_generator, the container can simply be stopped and/or removed:
+
+```
+$ docker stop $CONFIGMAP_GENERATOR_ID
+```
+
+```
+$ docker rmi --force manageiq/httpd_configmap_generator:latest
+```
+
+___
+
+
+## Running with OpenShift
+
+### Pre-deployment tasks
+
+#### If running without OCI systemd hooks (Minishift)
+
+The httpd-configmap-generator service account must be added to the miq-sysadmin SCC before the Httpd Auth Config pod can run.
+
+##### As Admin
+
+```
+$ oc adm policy add-scc-to-user miq-sysadmin system:serviceaccount:<your-namespace>:httpd-configmap-generator
+```
+
+Verify that the httpd-configmap-generator service account is now included in the miq-sysadmin SCC:
+
+```
+$ oc describe scc miq-sysadmin | grep Users
+Users:        system:serviceaccount:<your-namespace>:httpd-configmap-generator
+```
+
+#### If running  with OCI systemd hooks
+
+##### As Admin
+
+```
+$ oc adm policy add-scc-to-user anyuid system:serviceaccount:<your-namespace>:httpd-configmap-generator
+```
+
+Verify that the httpd-configmap-generator service account is now included in the miq-sysadmin SCC:
+
+```
+$ oc describe scc anyuid | grep Users
+Users:        system:serviceaccount:<your-namespace>:httpd-configmap-generator
+```
+
+
+### Deploy the Httpd Configmap Generator Application
+
+As basic user
+
+```
+$ oc create -f templates/httpd-configmap-generator-template.yaml
+
+$ oc get templates
+NAME                        DESCRIPTION                                 PARAMETERS     OBJECTS
+httpd-configmap-generator   Httpd Configmap Generator                   6 (all set)    3
+```
+
+Deploy the Httpd Configmap Generator
+
+```
+$ oc new-app --template=httpd-configmap-generator
+```
+
+Check the readiness of the Httpd Configmap Generator
+
+```
+$ oc get pods
+NAME                                READY     STATUS    RESTARTS   AGE
+httpd-configmap-generator-1-txc34   1/1       Running   0          1h
+```
+
+#### Getting the POD Name
+
+For working with the httpd\_configmap\_generator script in the httpd-configmap-generator pod, it is necessary to
+get the pod name reference below:
+
+
+```
+$ CONFIGMAP_GENERATOR_POD=`oc get pods | grep "httpd-configmap-generator" | cut -f1 -d" "`
+```
+
+
+### Generating a configmap for external authentication against IPA
+
+```
+$ oc rsh $CONFIGMAP_GENERATOR_POD httpd_configmap_generator ipa ...
+```
+
+Example configuration:
+
+```
+$ oc rsh $CONFIGMAP_GENERATOR_POD httpd_configmap_generator ipa \
+    --host=miq-appliance.example.com    \
+    --ipa-server=ipaserver.example.com  \
+    --ipa-domain=example.com            \
+    --ipa-realm=EXAMPLE.COM             \
+    --ipa-principal=admin               \
+    --ipa-password=smartvm1             \
+    -o /tmp/external-ipa.yaml
+```
+
+`--host` above must be the DNS of the application exposing the httpd auth pod,
+
+i.e. ${APPLICATION_DOMAIN}
+
+
+Copying the new auth configmap back locally:
+
+```
+$ oc cp $CONFIGMAP_GENERATOR_POD:/tmp/external-ipa.yaml ./external-ipa.yaml
+```
+
+The new configmap can then be applied to the auth httpd pod and then redeployed to take effect:
+
+```
+$ oc replace configmaps httpd-auth-configs --filename ./external-ipa.yaml
+```
+
+To generate a new auth configuration map it is recommended to redeploy the httpd\_configmap\_generator
+pod first to get a clean environment before running the httpd\_configmap\_generator tool.
+
+When done generating an auth-configmap, the httpd\_configmap\_generator pod can simply be scaled down:
+
+```
+$ oc scale dc httpd-configmap-generator --replicas=0
+```
+
+or deleted if no longer needed:
+
+```
+$ oc delete all  -l app=httpd-configmap-generator
+$ oc delete pods -l app=httpd-configmap-generator
+```