OpenID Connect is an authentication protocol that enables applications to authenticate users with external authentication services, referred to as OpenID Providers, such as: email, social networks or IAM systems without the user needing to send credentials to the application. It also allows applications to query information about a user to build up a full identity that can be used for authorization. With OpenID Connect, how the user authenticates is controlled by the OpenID Providers and so enables applications to support multiple different authentication mechanisms without modifying the application code to implement them.

In this blog post we will look at how you can configure your IBM MQ Console to use the openidConnectClient feature to enable you to authenticate queue manager administrators with an OIDC server. For this blog post I used the App ID service available in IBM Cloud to act as my OIDC server for authenticating users; however, in theory you could use other OIDC servers such as Azure AD, Google IAM, Keycloak or Okta.

Contents

• Introduction
• Configuring the App ID service
• Configuring MQ Console with the openidconnectclient feature
• Testing it out
• Conclusions

Introduction

The diagram above shows how we will integrate App ID into our IBM MQ network, in this case we will use it for authorizing access to the MQ Console. Any users who connect to the MQ Console will be redirected to the OIDC server to authenticate. Once they have authenticated, they will be redirected back to the MQ Console with a token that we will accept to authorize them and grant them access.

To implement this, we need to first configure the App ID service to be able to handle users that are sent to it to authenticate. This requires registration of both the MQ Console and the users we want to allow. Once the App ID service is configured, we can then configure the MQ Console to be able to use the service both to redirect users to it and grab the necessary information from the App ID service once they return to authorize them.

Configuring the App ID service

Before we can configure the App ID service for our needs, we need to first provision an instance of it. Locate the App ID service in the IBM Cloud Catalog

I called my instance App ID-ux and chose the free plan as this was sufficient for trialling the service. I made sure to deploy the service instance in the London data centre just because that was closest to where I am located. Everything else I left as defaults. Once the instance was deployed, I was greeted by the welcome page and could start with the next task:

Configuring the user registry

App ID hosts several user registries that it can integrate with by default as well as the ability to also integrate with other registries via the Custom Identity feature. It also supports hosting its own user registry via the Cloud Directory feature. For this blog post I used this functionality to quickly define the users I want to grant access to my MQ Console.

You can find the identity providers underneath the Manage Authentication menu item. Once you have reached the menu you need to enable the cloud directory using the switch on the right.

With the cloud directory enabled we need to configure it a bit. There are many options here including password policies, sign up capabilities and Multi-factor Authentication. However, in this blog post all we need is to define the Users. Select Users in the Cloud Directory menu option on the left. Here you can click create and add users you want to authorize into your MQ Console.

I defined 3, one for me, one for Dave Ware and one for Matt Leming

At this point we now have 3 users that we can login with later when we try to access our MQ Console.

Registering my application

Before we can configure the MQ Console we need to obtain credentials and authority for the MQ Console to be able to access the App ID service to authorize users. Without this, the App ID server will reject any attempts to communicate with it including rejecting browsers that are redirected to it.

There are two things we need to do:

• Register the MQ Console with App ID
• Register the redirect URL with App ID

To register the MQ Console, we navigate to the Applications menu and select Add application.

{
  "clientId": "<ClientID>",
  "tenantId": "<tenantID>",",
  "secret": "<secret>",",
  "name": "mqclient",
  "oAuthServerUrl": "https://eu-gb.appid.cloud.ibm.com/oauth/v4/<tenantID>",
  "profilesUrl": "https://eu-gb.appid.cloud.ibm.com",
  "discoveryEndpoint": "https://eu-gb.appid.cloud.ibm.com/oauth/v4/<tenantID>/.well-known/openid-configuration",
  "type": "regularwebapp",  "scopes": []
}

Make a note of the following: clientId, secret, discoveryEndpoint for later.

Next, we need to register the redirect URL so App ID. When the MQ Console redirects a user connecting it includes information for App ID on where to redirect the user back to once they have authenticated. The MQ Console, or more appropriately Liberty, expects returning users to go to the following URL:

https://<host>:<port>/oidcclient/redirect/<ID>

Where <host>:<port> is where the MQ Console is running and <ID> is the identity we give the openidConnectClient feature in the MQ Console configuration. Currently we have not chosen that but for this blog post I used mqclient.

In App ID navigate back to the Manage Authentication menu but this time go to the Authentication settings tab instead of Identity providers. Here we can see a box to Add web redirect URLS to add the appropriate redirect URL.

Final touches

At this point App ID is configured so that we can connect our MQ Console to it and redirect users to it to authenticate. So long as they are one of the users we added to the Cloud Directory they will be able to authenticate and be redirected back to the MQ Console.

Before we start with the MQ Console configuration we can customize the login screen that users are presented when they get redirected to the App ID service. Select the Login Customization menu item and modify whatever setting you like. I added the IBM MQ logo, changed the header colour to green and modified the tab name and footnote:

Configuring MQ Console with the openidconnectclient feature

At this point our App ID service is configured and ready to receive our redirected users. We now need to create our MQ Console configuration. In the <MQ Data>/web/installations/<installation name>/servers/mqweb folder create a new file called mqwebuser.xml and add the following:

<?xml version="1.0" encoding="UTF-8"?>
<server>
    <featureManager>
        <feature>openidConnectClient-1.0</feature>
        <feature>transportSecurity-1.0</feature>
    </featureManager>

    <!-- Console users -->
    <enterpriseApplication id="com.ibm.mq.console">
        <application-bnd>
            <security-role name="MQWebAdmin">
                <special-subject type="ALL_AUTHENTICATED_USERS"/>
            </security-role>
        </application-bnd>
    </enterpriseApplication>

    <!-- The OIDC configs -->
    <openidConnectClient id="mqclient"
        clientId="<ClientID>"
        clientSecret="<ClientSecret>""
        discoveryEndpointUrl="<DiscoveryURL>" >
    </openidConnectClient>

    <!-- Additional security settings-->
    <webAppSecurity sameSiteCookie="lax"/>
    <webAppSecurity ssoRequiresSSL="true"/>
    <webAppSecurity trackLoggedOutSSOCookies="true"/>
    <variable name="httpHost" value="localhost"/>
    <variable name="httpsPort" value="9443"/>
    <virtualHost allowFromEndpointRef="defaultHttpEndpoint" id="default_host">
        <hostAlias>localhost:9443</hostAlias>
    </virtualHost>

    <!-- SSL location -->
    <keyStore id="MQWebKeyStore" location="C:/tmp/wlp.p12" type="PKCS12" password="wibble"/>
    <keyStore id="MQWebTrustStore" location="C:/tmp/trust.p12" type="PKCS12" password="wibble"/>
    <ssl id="thisSSLConfig" keyStoreRef="MQWebKeyStore" trustStoreRef="MQWebTrustStore" serverKeyAlias="default" sslProtocol="TLSv1.2" />
    <sslDefault sslRef="thisSSLConfig"/>
</server>

Note: If you already have configured the MQ Console, the above configuration shows the minimum needed to enable the openidConnectClient feature. It may be possible to merge the above in, but you must pay careful attention if have already implemented a user registry (user, LDAP, or TLS certificates) as this could conflict with the openidConnectClient feature.

There are a lot of settings here so let us break it down into what each part does:

    <featureManager>
        <feature>openidConnectClient-1.0</feature>
        <feature>transportSecurity-1.0</feature>
    </featureManager>

Here we enable the two features we need, the openidConnectClient feature is obvious but we also want the transportSecurity feature to ensure secure communications with App ID.

    <enterpriseApplication id="com.ibm.mq.console">
        <application-bnd>
            <security-role name="MQWebAdmin">
                <special-subject type="ALL_AUTHENTICATED_USERS"/>
            </security-role>
        </application-bnd>
    </enterpriseApplication>

This is the main setting for the MQ Console to tell it what to do with a user after Liberty has authenticated them with the App ID service. Here I have configured it so that all users that successfully authenticate are granted the MQWebAdmin role, which converts them to the mqm user when interacting with queue managers.

    <openidConnectClient id="mqclient"
        clientId="<ClientID>"
        clientSecret="<ClientSecret>""
        discoveryEndpointUrl="<DiscoveryURL>" >
    </openidConnectClient>

Here we configure the openidConnectClient feature with the information it needs to send incoming connections to the App ID service. It looks quite light, but this is because most of the heavy lifting is done by the discoveryEndpointUrl setting which points to the App ID service’s external configuration which liberty can parse. If your OIDC server does not support the OIDC discovery specification, then you will need to provide this information manually.

As well as a link to the discovery endpoint we also need to pass the ClientID and clientSecret we got when we configured the application in App ID earlier and an ID. This ID must match the redirect URL exactly as we set it in App ID. Earlier, I set the redirect URL to be https://localhost:9443/oidcclient/redirect/mqclient where the last part is the ID we need to use.

There are a number of other configuration options that you can use to fine tune your configuration, these are detailed in the WebSphere Liberty documentation for the openidConnectClient feature: https://www.ibm.com/docs/en/was-liberty/nd?topic=configuration-openidconnectclient

    <webAppSecurity sameSiteCookie="lax"/>
    <webAppSecurity ssoRequiresSSL="true"/>
    <webAppSecurity trackLoggedOutSSOCookies="true"/>
    <variable name="httpHost" value="localhost"/>
    <variable name="httpsPort" value="9443"/>
    <virtualHost allowFromEndpointRef="defaultHttpEndpoint" id="default_host">
        <hostAlias>localhost:9443</hostAlias>
    </virtualHost>

There are several settings here that are optional but provide a bit of extra customization. The only setting here that I found was necessary was sameSiteCookie="lax”, without this setting when the App ID service redirected me back to liberty it seemed that liberty would have forgotten who I was and reject me with the following error:

The remaining settings ensure that TLS is used to communicate with the MQ Console and App ID service.

    <keyStore id="MQWebKeyStore" location="C:/tmp/wlp.p12" type="PKCS12" password="wibble"/>
    <keyStore id="MQWebTrustStore" location="C:/tmp/trust.p12" type="PKCS12" password="wibble"/>
    <ssl id="thisSSLConfig" keyStoreRef="MQWebKeyStore" trustStoreRef="MQWebTrustStore" serverKeyAlias="default" sslProtocol="TLSv1.2" />
    <sslDefault sslRef="thisSSLConfig"/>

Finally, this configuration is standard for TLS communications, I have provided my own certificate to use with the console so I can connect to it securely.

Testing it out

At this point our App ID service is configured and ready to authenticate users; our MQ Console has also been configured to redirect connections to the App ID service when they first connect to authenticate. Once successfully authenticated WebSphere liberty will pass their details onto the MQ Console which will accept the user as an administrator of MQ.

To test this, we start up the MQ Console and then open a web browser to try and connect to it. You will find you that must go to either https://localhost:9443/ or https://localhost:9443/ibmmq/console otherwise you may end up being redirected to the MQ Console login page, which cannot be used as we have no User Registry defined.

When you try to access the MQ Console you will be redirected to the login page which has the customization setup earlier:

Conclusions

At this point any user who can authenticate to App ID will be granted admin access to any MQ Console that has been configured to use it for Authentication. However, in most cases this is too open, and we need to have a level of granularity to ensure that only a set of users can access the MQ consoles they are allowed to. In the next blog post we will look at the options for fine grain control over what users from the OIDC Server can access the MQ Console. You can read part 2 here.