It has been some time since I last wrote about new capabilities in our on-premises access management offering (formerly IBM Security Access Manager, now IBM Security Verify Access). In this article I’m going to share some history, and discuss one of my favorite recently added capabilities – something I personally asked the development team to introduce to make my life easier.
Scenario
I often find myself building and demonstrating authentication and access management scenarios on top of IBM Security Verify Access, and more recently the container-based web reverse proxy we call (for now anyway) IBM Application Gateway. Many of you may have visited one or more of the demonstration sites that I have built. Any time I do this, I am either creating, manipulating or performing authorization decisions based on the session credential of the end-user. To do that effectively, you have to know what the session credential contains. The groups and attributes in the user’s session are used for so many things including authorization decisions, downstreaming attributes via header to junctioned applications and building attributes in SAML assertions or OIDC id_tokens via mapping rules for federated SSO. Without visibility into what the session credential contains, you cannot make effective design and configuration decisions.
I have written about the importance of having the ability to introspect your session credentials on many occasions, starting way back in 2007 with Practical TAM Authorization API. I believe my most recent variation on the theme was in 2018 with: Implementing an ISAM credential viewer in Infomap. The history of the session credential format in IBM Security Verify Access is a story of its own. You may simply know it as “the iv-creds header”, or hear it described as a PAC (privileged attribute certificate) or EPAC (extended privileged attribute certificate). In fact this is why my first article on the topic described writing epac.jsp to introspect the value of the iv-creds header on a junctioned WebSphere application server. Historically this technology dates back more than 20 years to the mid 1990’s and the era of DCE (Distributed Computing Environment). It is from DCE that the EPAC format was derived. Under the covers it’s a rather complicated ASN.1 data structure that modern developers have no interest (nor should they need) to understand. Instead we want the same information in cleartext, or newer flavour-of-the-month formats such as JSON or JWT. At the end of the day the format used inside the reverse proxy itself doesn’t matter so much, so long as we have a way to understand and visualize what it contains.
As of IBM Security Verify Access version 10, you no longer need an external application or complicated Infomap/STS configuration to gain complete insight into the user’s credential – there is a capability built directly in the web reverse proxy (formerly known as WebSEAL) to do this for you. I’m going to show you two ways to use it that I find useful during my development and POC-building activities. This capability is available both in the full IBM Security Verify Access product, and in the IBM Application Gateway container offering.
Configuration and Demo
I’m going to assume if you’re still reading that you are familiar with IBM Security Verify Access, have a Web Reverse Proxy (WRP) configured, and a way of logging in to it, whether that be via a local account with username, password, etc, or via federation. What you want at this point is to be able to see the credential attributes.
For IBM Security Verify Access
The information center detail on this capability is here, or to shortcut it all, just go to your WebSEAL configuration file and update these stanza entries:
[local-apps]
cred-viewer=ivcreds
For IBM Application Gateway
The configuration documentation for IAG is here, and the basic configuration in YAML format:
server:
local_applications:
cred_viewer:
path_segment: "ivcreds"
Viewing the credential attributes in a browser
Regardless of which product offering you are using, there are more detailed configuration instructions included in the documentation which permit filtering of attributes returned to the client, disabling the HTML display capability (you can use the endpoint for JSON responses as we will see shortly), and of course changing the URL path to the viewer itself.
Either way, login to your reverse proxy and view the credential as shown simply by accessing the /ivcreds url (this is a truncrated screenshot):
If you go a step further and attach an unauthenticated-allowed ACL to the /ivcreds resource (or use equivalent authorization policy in IAG), you can also see the credential for unauthenticated users instead of getting a login challenge. This is particularly useful when the capability is used for JSON responses, which we will now cover.
Obtaining JSON responses
The credential viewer local application is accept-header-aware. By default it will return a HTML page as shown above, however if you wish to receive a JSON response your request should contain the header:
Accept: application/json
This is particularly useful in scripted applications (e.g. using cURL with OAuth access tokens), or when developing a single-page-application (SPA) which invokes the credential viewer URL via AJAX/fetch.
Let’s look at a simple example that makes use of the new credential viewer local application via the fetch API. It’s small enough to include the entire HTML source code right here, and you can save this page in your reverse project document root and access it from the browser (I called it landing.html):
<html>
<head>
<script src = "https://code.jquery.com/jquery-1.11.3.min.js"></script>
<script type="text/javascript">
function getBaseURL() {
var locationHostPort = location.hostname+(location.port ? ':'+location.port: '');
var baseURL = location.protocol+'//'+locationHostPort;
return baseURL;
}
function onLoad() {
fetch(
getBaseURL() + "/ivcreds",
{
headers: { "Accept": "application/json" }
}
).then((response) => {
return response.json();
}).then((data) => {
$('#username').text(data["AZN_CRED_PRINCIPAL_NAME"]);
}).catch((e) => {
console.log("Error fetching ivcreds: " + e);
});
}
</script>
</head>
<body onload="onLoad()">
Hello: <b><span id="username"></span></b>
</body>
</html>
Accessing the resource in the browser results in:
Of course you can think of more useful applications of the JSON-based approach, and have access to all the attributes in the credential (subject to any filtering out done by configuration at the server).
If you are a practitioner of IBM’s on-premises access management technologies I hope you will appreciate how useful this new capability is, particularly during the development of new solutions and access policies, as well as for runtime use in single page applications. I now use it in every demonstration environment I build!
#SecurityExpert