Merge pull request #278 from shreeya1510/shreeya-jwt

adding documentation for jwt authentication

README.md

@@ -107,6 +107,20 @@ main `samples` directory, that all the samples use for default configuration set
     }]
 }
 ```
+### JWT
+
+Use the following environment variables for the JWT enabled samples. These applications use this endpoint to request and retrieve a token. [JWT README](jwt-jwks-docs/README.md)
+
+```JSON
+"JWT_ISSUER" : {
+    "JWT_TOKEN_ENDPOINT":"https://<KEYCLOAK_URL>/realms/master/protocol/openid-connect/token",
+    "JWT_TOKEN_USERNAME":"app",
+    "JWT_TOKEN_PWD":"passw0rd",
+    "JWT_TOKEN_CLIENTID":"admin-cli"
+}
+```
+The `"JWT_TOKEN_ENDPOINT"` points your sample to a keycloak server(token issuer), which could be running in a container. 
+The `"JWT_TOKEN_USERNAME"` and `"JWT_TOKEN_PWD"` come from your keycloak "app" user credentials, that you would have configured via the keycloak console.
 
 ### IBM Z Xplore
 If you are running these samples on IBM Z Xplore then you can use the `env-zbindings.json` file. Simply rename the

env.json

@@ -40,7 +40,7 @@
     "TOPIC_NAME": "dev/"
   }],
   "JWT_ISSUER" : {
-    "JWT_TOKEN_ENDPOINT":"http://<KEYCLOAK_URL>/realms/master/protocol/openid-connect/token",
+    "JWT_TOKEN_ENDPOINT":"https://<KEYCLOAK_URL>/realms/master/protocol/openid-connect/token",
     "JWT_TOKEN_USERNAME":"app",
     "JWT_TOKEN_PWD":"passw0rd",
     "JWT_TOKEN_CLIENTID":"admin-cli"

jwt-jwks-docs/README.md

@@ -0,0 +1,79 @@
+# Steps to connect a Sample Application to an IBM MQ Queue Manager using JWT with JWKS 
+
+*coming soon* You can find a more in-depth step-by-step tutorial on IBM Developer(https://developer.ibm.com/components/ibm-mq/tutorials/).
+
+## 1. Set up a keycloak server in a container 
+
+• Open up a terminal and create a keystore using openssl, for your keycloak server (token issuer).
+
+``` mkdir keycloakKeystore ```
+
+``` openssl req -newkey rsa:2048 -nodes -keyout keycloakKeystore/keycloakPrivate.pem -x509 -days 365 -out keycloakKeystore/keycloakPublic.pem -subj "/C=GB/ST=MYSTATE/L=MYCITY/O=MYORG, Inc./OU=IT/CN=<hostname>" ```
+
+``` openssl pkcs12 -inkey keycloakKeystore/keycloakPrivate.pem -in keycloakKeystore/keycloakPublic.pem -export -out keycloakKeystore/keycloak.p12 ```
+
+``` chmod 770 keycloakKeystore && chmod 440 keycloakKeystore/keycloak.p12 ```
+
+• Then, you can start your keycloak server.
+
+```podman run -p 32030:32030 -e KEYCLOAK_ADMIN=kcadmin -e KEYCLOAK_ADMIN_PASSWORD=passw0rd -v /path/to/keycloakKeystore/:/path/to/keycloakKeystore/   quay.io/keycloak/keycloak:latest start --hostname-strict=false --https-key-store-file=/path/to/keycloakKeystore/keycloak.p12 --https-key-store-password=password --https-port=32030 ```
+
+• Open up a web browser, and go to your JWKS endpoint (https://<hostname>:32030/). 
+
+• Sign in using your admin credentials (that you set up when starting your keycloak server - hint: check the previous run command).
+
+• Once logged in, go to: `clients` > `admin-cli` > `advanced` > `advanced settings` > turn the `lightweight token` off
+
+• Now, go to: `Users` > `Add user` > call your user "app" > `create` > `credentials` > set a password > turn `Temporary` off 
+
+
+## 2. Configure your queue manager to accept authentication via JWKS
+
+• Firstly, ensure you have a queue manager running in a container.
+
+• The configuration for your queue manager along with the samples can be found in this repo.
+
+```git clone https://github.com/ibm-messaging/mq-dev-patterns.git ```
+
+• You can find the queue manager configuration in this directory [queue manager config](qm.ini)
+
+• The JWKS stanza in this file needs to be edited appropriately, either in an editor or terminal.
+
+• Now you can copy this file back into your queue manager along with the keycloak server’s public certificate:
+
+``` podman cp qm.ini QM1:/var/mqm/qmgrs/QM1/ ```
+
+``` podman cp keycloakKeystore/keycloakPublic.pem QM1:/var/mqm/qmgrs/QM1/ssl/ ```
+
+• Next, we will need command line access inside the queue manager to create your queue manager’s keystore and import the keycloak public key.
+
+``` podman exec -ti QM1 bash```
+
+``` opt/mqm/bin/runmqakm -keydb -create -db /var/mqm/qmgrs/QM1/ssl/mqdefcer.p12 -pw password -type pkcs12 -stash ```
+
+``` runmqakm -cert -add -db /var/mqm/qmgrs/QM1/ssl/mqdefcer.p12 -pw password -label keycloakPublicLabel -file /var/mqm/qmgrs/QM1/ssl/keycloakPublic.pem ```
+
+• Refresh security inside the Queue Manager so that it can recognise the JWKS endpoint and read the keystore
+
+```runmqsc```
+```REFRESH SECURITY```
+
+## 3. Configure and run client
+
+• Your samples need to connect to the keycloak server, to do so they will need their own keystore. The keycloak's public certificate will need to be imported into this keystore.
+
+### JMS 
+
+• If you want to run our JMS samples, create your Java keystore and import the keycloak public key.
+
+``` keytool -importcert -file keycloakKeystore/keycloakPublic.pem -keystore clientkey.jks -alias "jmsClientHttps " ```
+
+• Edit the env.json, so that it has a single MQ endpoint and the JWT issuer config block has the appropriate values. The username and password here are the"app" user credentials you would have set up earlier, via the keycloak console.
+
+• Then, you can build and run your client!
+
+``` cd JMS ```
+
+``` mvn clean package ```
+
+```java -Djavax.net.ssl.trustStore=/path/to/clientkey.jks -Djavax.net.ssl.trustStorePassword=password  -cp target/mq-dev-patterns-0.1.0.jar com.ibm.mq.samples.jms.JmsPut ```

jwt-jwks-docs/qm.ini

@@ -0,0 +1,77 @@
+#*******************************************************************#
+#* WARNING: Automatic configuration has been enabled for this      *#
+#* queue manager. Modifications in this file to anything other     *#
+#* than valid AutoConfig keys will be lost at the next Queue       *#
+#* Manager start.  To disable automatic ini configuration, remove  *#
+#* the 'IniConfig' key from the AutoConfig stanza.                 *#
+#*******************************************************************#
+#
+#*******************************************************************#
+#* Module Name: qm.ini                                             *#
+#* Type       : IBM MQ queue manager configuration file            *#
+#  Function   : Define the configuration of a single queue manager *#
+#*                                                                 *#
+#*******************************************************************#
+#* Notes      :                                                    *#
+#* 1) This file defines the configuration of the queue manager.    *#
+#* 2) The LogFilePages attribute is read-only and changes to it    *#
+#*    will have no effect.                                         *#
+#* 3) The LogType attribute is read-only and changes to it will    *#
+#*    have no effect. To change the log type of the queue manager  *#
+#*    use the migmqlog command.                                    *#
+#*                                                                 *#
+#*******************************************************************#
+ExitPath:
+   ExitsDefaultPath=/mnt/mqm/data/exits
+   ExitsDefaultPath64=/mnt/mqm/data/exits64
+#*                                                                 *#
+#*                                                                 *#
+Log:
+   LogPrimaryFiles=3
+   LogSecondaryFiles=2
+   LogFilePages=4096
+   LogType=CIRCULAR
+   LogBufferPages=0
+   LogPath=/mnt/mqm/data/log/QM1/
+   LogWriteIntegrity=TripleWrite
+Service:
+   Name=AuthorizationService
+   EntryPoints=14
+   SecurityPolicy=UserExternal
+
+SSL:
+   AllowTLSV13=Yes
+   MinimumRSAKeySize=1
+   HTTPSKeyStore=/var/mqm/qmgrs/QM1/ssl/mqdefcer.p12
+Channels:
+   ChlauthEarlyAdopt=Yes
+   ChlauthIgnoreUserCase=No
+TCP:
+   SndBuffSize=0
+   RcvBuffSize=0
+   RcvSndBuffSize=0
+   RcvRcvBuffSize=0
+   ClntSndBuffSize=0
+   ClntRcvBuffSize=0
+   SvrSndBuffSize=0
+   SvrRcvBuffSize=0
+   SecureCommsOnly=NO
+AutoConfig:
+   MQSCConfig=/etc/mqm/
+   IniConfig=/etc/mqm/
+Subpool:
+   ShortSubpoolName=QM10000
+ServiceComponent:
+   Service=AuthorizationService
+   Name=Dev.HtpAuth.Service
+   Module=/opt/mqm/lib64/mqsimpleauth.so
+   ComponentDataSize=0
+ServiceComponent:
+   Service=AuthorizationService
+   Name=MQSeries.UNIX.auth.services
+   Module=amqzfu
+   ComponentDataSize=0
+JWKS:
+   IssuerName=https://<hostname>:32030/realms/master
+   Endpoint=https://<hostname>:32030/realms/master/protocol/openid-connect/certs
+   UserClaim=preferred_username