These are my assets for deploying the IBM Application Gateway (IAG). These assets are for version 21.12.
These assets are used in my IAG Deployment cookbook: https://ibm.biz/iagcookbook
The IBM Application Gateway requires an IBM Verify Tenant for authentication. For information on setting up a free trial tenant, check out https://ibm.biz/cloudidcookbook (Exercises 1 and 2).
You will need to configure a Custom Application with these settings:
- Sign-in Method: Open ID Connect 1.0
- Grant Types: Authorization Code
- Redirect URL: <Route>/pkmsoidc (e.g. https://*.127.0.0.1.nip.io/pkmsoidc)
Once this application is created, you can get the Client ID and Client Secret which you will need to configure IAG.
With the exception of the "Hello World" OpenShift template, all other deployments in this repository expect to use a pre-created certificate+key for the IAG HTTPS connection. In the common directory is a script which will create a certificate+private key for the front end of the application gateway. This script will create the certificate with extended key usage and lifetime set so that it is accepted by latest Firefox and Chrome browsers.
common/create-iag-crypto.sh
A certkey.pem file is created which can be mounted to the IAG container (either via a host mount or via a secret).
The IAG deployments created by the assets in this repository, read environment variables from the container. These are populated (in different ways) from the common/config.properties file.
Copy the sample file:
cp common/config.properties.sample common/config.properties
and then edit common\config.properties and fill in your information.
Native Docker assets are in the docker folder. If you want to build a Docker test system you can use this asset:
A script is provided for starting the IAG in a native Docker container. This script has the following usage:
docker/iag-run.sh <config-directory> <publish host>:<port>
For example:
docker/iag-run.sh configs/hello-world 127.0.0.1:443
The IAG is now running. Use a browser to connect using the host and port you specified.
Stop and remove the IAG docker container:
docker rm -f iag-<config name>
Clean up the bind mount directories:
rm -rf docker/mounts
OpenShift assets are in the openshift folder. If you want to build an OpenShift test system you can use these assets:
- OKD on Centos 7 (https://ibm.biz/isamopenshiftbuild)
- OKD on MacOS (https://ibm.biz/openshiftmac)
A "Hello World" OpenShift template is provided which can be deployed to test the IAG.
oc create -f openshift/iag-hello-world.yaml
Once you have created this template, use the OpenShift console to deploy it. you will need to complete the Verify OIDC Discovery Endpoint, OIDC Client ID, and OIDC Client Secret in the template deployment wizard.
Once deployed, use the Route to connect to the IAG. You will be redirected to your Verify tenant to authenticate.
Once authenticated, you can request the /cred-viewer url to see the attributes provided by Verify.
e.g. https://iag-hello-world.127.0.0.1.nip.io/cred-viewer
A script is provided that will create a Secret and ConfigMap from environment specific information. The iag Secret will contain:
- All files in the common/secret_files folder
- All attributes from common/config.properties that start S_
The iag ConfigMap will contain:
- All files in the common/env_files folder
- All attributes from the common/config.properties that do not start S_
The iag.certkey.pem file is required in the common/secrets folder. If it doesn't exist, the create-iag-crypto.sh script will be called to generate it.
openshift/create-iag-assets.sh
In this case you load your configuration assets into entries of a ConfigMap object. This ConfigMap is then mounted to the /var/iag/config directory of the IAG container.
Create a config map containing your configuration:
oc create configmap iag-config --from-file=configs/hello-world/src/
Install the template:
oc create -f openshift/iag-configmap-template.yaml
Now open the OpenShift UI (e.g. https://localhost:8443), select project, and go to catalog. You will see icon for the application. Click to deploy. You can change parameters before deploy. Parameters include the configuration configMap and the Secret and ConfigMap generated by the create-iag-assets.sh script.
In this case your configuration files are downloaded from a source repository and baked into a new Docker image by a BuildConfig. The new image is loaded to an ImageStream which a DeploymentConfig then uses to create the IAG containers.
A sample "Hello World" repository is pre-configured in the template parameters.
Install the template:
oc create -f openshift/iag-build-template.yaml
Now open the OpenShift UI (e.g. https://localhost:8443), select project, and go to catalog. You will see icon for the application. Click to deploy. You can change parameters before deploy. Parameters include the Secret and ConfigMap generated by the create-iag-assets.sh script.
You can uninstall all assets associated with the IAG (iag is default app name) using these commands:
oc delete all -l app=iag
oc delete secret iag
oc delete configmap iag
Kubernetes assets are in the kubernetes folder. If you want to build a Kubernetes test system you can use this asset:
- Kubernetes on Centos 7 (https://ibm.biz/isamkubebuild)
A script is provided that will create a Secret and ConfigMap from environment specific information. The iag Secret will contain:
- All files in the common/secret_files folder
- All attributes from common/config.properties that start S_
The iag ConfigMap will contain:
- All files in the common/env_files folder
- All attributes from the common/config.properties that do not start S_
The iag.certkey.pem file is required in the common/secrets folder. If it doesn't exist, the create-iag-crypto.sh script will be called to generate it.
kubernetes/create-iag-assets.sh
You will load your configuration assets into entries of a ConfigMap object. This ConfigMap is then mounted to the /var/iag/config directory of the IAG container.
Create a config map containing your configuration:
kubectl create configmap iag-config --from-file=configs/hello-world/src/
Create the Kubernetes assets using the provided YAML file:
kubectl create -f kubernetes/iag.yaml
You can uninstall all assets associated with the IAG using these commands:
kubectl delete deploy iag
kubectl delete service iag
kubectl delete ingress iag
kubectl delete secret iag
kubectl delete configmap iag
kubectl delete configmap iag-config
A demo NodeJS application is provided in the repository. This can be used to test out single sign-on from the IAG. npm is required to install and run this application.
The demo application listens on HTTPS. To generate a key+certificate for this, run the following script:
common/create-demoapp-crypto.sh
demoapp.cert.pem and demoapp.key.pem files are created in the common/demoapp directory where the application will look from them.
The demoapp.cert.pem file is also copied to the common/env_files directory. This makes it available to the IAG which is required for it's connection verification.
Go to the demo application directory:
cd common/demoapp
(Once only) install the application modules:
npm install
Start the application (it runs in the foreground):
npm start
The contents of this repository are open-source under the Apache 2.0 licence.
Copyright 2019-2022 International Business Machines
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.