OAuth: Building a developer portal

Share this post:

OAuth: Developer Portal

Create a self-service portal for OAuth clients to significantly reduce costs for ISAM administrators


OAuth as a protocol delegates the authorization decision to the resource owner, which means that the consumer of a given resource does not need to be explicitly permitted to access that resource up to the moment that an authorization is requested (and thus the resource owner is prompted if they permit this authorization decision). What this means is that OAuth is well suited to third-party API consumption, allowing an unknown or not highly trusted entity to request and potentially consume APIs on behalf of a user. In order for an application to consume APIs on behalf of a user, it requires a client-id , which is used to identify to the authorization server that is requesting access. The method by which these client IDs are issued to users is not defined well; an administrator might be responsible for creating the client and providing the details to the application owner in an out-of-band way. This process can be cumbersome, particularly in a world that is shifting its focus to cloud.

image (4)

Why self-service clients?

As the number of cloud applications increase, the onboarding process and ongoing maintenance of clients becomes an ever increasing cost for administrators. The solution to this increased bandwidth and cost is to allow users (who are trusted sufficiently) to request and manage the client registrations for applications that they own. Allowing users management responsibilities shifts the trust of the application from the administrator onto the application owner, so you must consider several things. The consent step should now be mandatory, such that users are informed to who they’re about to delegate access to and the client registration may also wish to enforce the presence of contact information, which is also shown to the user during consent, to allow the user to contact the app owner.

On ISAM, OAuth clients are registered as a member of an OAuth definition via the LMI. Using LMI means that in order for a third party to get the client credentials required to request resources, manual intervention from an administrator is traditionally required. However, new in ISAM 9040 is an API available in InfoMap. For some more uses of InfoMap, you can check out Shane’s blog. Read Phil’s blog to learn how you can register an OAuth client, and then propagate back, the new set of client credentials which can be used by a third party to request APIs.

Using a JavaScript API

The intended use of a JavaScript API is via the authentication service, to be used like the OOTB USC scenarios (create user/reset password/change password). This JavaScript API is not limited to InfoMap and it is also possible to use this API in a more service-oriented approach by using the WS-Trust SecurityTokenService.

The following section is a guide on how to produce USC flows, such that a developer persona can be directed through a USC flow to register an OAuth client and retrieve the required client credentials. Exposing such a portal seeks to reduce the ongoing cost of ownership for an ISAM administrator. The benefits of having a developer portal allows you to direct users of your service within a business rather than raising a ticket. This is not the only application of such a portal, but can be taken a step further where you can build a totally public identity provider by implementing OpenID Connect.

Best practices for registering OAuth clients

The following are suggestions and best practices when allowing users to register OAuth clients:

  •  Require user consent, which can be configured on the OAuth definition.
  •  Enforce that https:// is the protocol of the clients’ redirect URI.
  •  Only allow users which a sufficient level of trust to create OAuth clients.
    This can be achieved by a combination of a complete user profile (email address, phone
    number, company name, and company URL), and at the time of authentication, forcing a
    further validation of the user’s identity via second-factor authentication.
  •  Strict enforcement around well-formed OAuth requests. Require the use of the redirect_uri ,
    state , and nonce parameters.
  •  Enforce the use of confidential clients.
  •  Configure the OAuth definition in a restrictive manner, which includes:
    •  Grant types support
    •  Token lengths
    •  Short lived tokens
    •  Not issuing refresh tokens unless necessary
    •  Rate limit client IDs


App Exchange

This deployment uses the app exchange deployment pattern. You can find other app exchange integrations in ISAM under the identity and access topic at


Deploying the portal

The deployment of this portal is automated via the app-exchange installer. Simply download the bundle and run it.

Download the bundle HERE

In order to deploy this solution, there is a prerequisite of having a reverse proxy configured, and have it ready and integrated with the ISAM Authentication service. The usual facility for performing this is isamcfg.jar. (You can find out more on using at the Knowledge Center: Using the isamcfg tool. Additonally, an OAuth definition with the name “Example App” needs to be created.


Figure 1. Running the config tool

Running the tool

After configuring a reverse proxy, download the appx bundle above, and the Appx installer.

Figure 2. Configuring the “Example App” Definition:

Creating the definition

Figure 3. The help output for running the installer



Extract the zip and invoke the appx installer script, as seen in Figure 4.


Figure 4. Running the installer

Screenshot from 2018-05-31 18-20-45

The app is now ready to run and you are now able to experience the developer portal.
Figure 5. The new authentication policy added

The added Policy


Invoking the portal

There are four scenarios that are covered in this portal. Creating a client, viewing clients, updating a client, and removing a client. Before you perform any of these operations, the client owner needs to authenticate, which in this instance is via username/password. However, because this is all partof the authentication service, an administrator can easily layer further authentication requirements on the user.

Experience the portal by visiting this URL:



Figure 6. The developer portal

The dev portal

Figure 7. Managing an existing OAuth client

Managing A client



The client credentials can now be used in any fashion that is supported by the configured OAuth definition.
It’s worth noting that while this developer portal doesn’t expose any of the new fields added to a client in 9040, they are still available in the exposed API. This includes setting of: PKCE required, JWKS URI, Encryption database and certificate.


To debug the solution, the following trace strings are useful:


Clients do get cached in memory, so a deleted client may continue to operate for some time after it has been deleted or it may take some time to replicate after an update. The time in which clients are cached for can be modified by changing the advanced configuration parameter:



A big thank you to Jared Page for collaborating with me on this.

Click here to rate this article

Rate this article :

Software Engineer - IBM Security Access Manager

More Articles stories
By Leo Farrell on December 2, 2018

Web Reverse Proxy: Rate Limiting

Web Reverse Proxy: Rate Limiting   Rate limiting is the act of stopping a client from requesting web resources too often. The ISAM web reverse proxy now supports rate limiting on  as of version We identified rate limiting as something which is performed on one of two actors. A malicious actor who is trying […]

Continue reading

By Jeroen Tiggelman on November 10, 2018

IBM Security zSecure suite and solutions overview

zSecure for z/OS 2.3.1 contains the following products… zSecure Admin – efficient and effective RACF administration zSecure Visual – a Windows-based UI for RACF administration zSecure CICS Toolkit – RACF administration from a CICS environment zSecure Audit – vulnerability analysis for the mainframe zSecure Adapters for SIEM – manage events in QRadar or ArcSight zSecure Alert – real-time threat monitoring zSecure Command Verifier – […]

Continue reading

By Leo Farrell on November 7, 2018

Open ID Connect: Sharing identity information with Applications

Open ID Connect: Sharing identity information with Applications When developing modern web applications, information about the user is essential for providing a rich user experience. There are many ways in which this identity information is gathered. Applications may source user data many different ways. They may simply request the user supply user profile information on […]

Continue reading