An Introduction to Automated Configuration in IBM Security Access Manager v9

Over the past few years IBM Security has demonstrated intent to migrate access management and federation technologies from distributed platform software to a physical/virtual appliance delivery model. This has numerous benefits to both our customers and IBM, with middleware patch management ranking right up there amongst the most effort-saving. The appliance journey started with ISAM 7, which delivered the first ISAM-in-a-box offering including policy and web access management. In ISAM 8 the first of the capabilities traditionally offered by Tivoli Federated Identity Manager (TFIM) was added to the appliance platform – specifically context-based access and OAuth. In ISAM 9 the migration of federation capabilities to the appliance continues, with the major feature-adds being SAML 2.0 SSO, and a set of OpenID Connect browser-SSO use cases.

In my mind though, the real benefit of ISAM 9 is not just the functional capabilties that are being brought across from TFIM and additional enhancements being made to the appliance and WebSEAL. Without question I believe the biggest advantage over our software solutions is the ability to automate configuration via REST API’s. In fact I would go further and say this is the MOST valuable aspect of the appliance platform in general. It is automated configuration via REST that makes the appliance simpler to deploy, maintain and scale out.

One of my many roles at IBM is to deploy and maintain a production system that uses ISAM, run on Softlayer infrastructure. My environment has development, staging and production systems, all which support identical capability. Every single ISAM appliance in each of these environments is configured via automation, with a small manual step at the beginning to create a VM and assign a management IP address. Even this could be automated if I invested a bit more time in the VM creation process. The configuration of the appliances is done via REST client code and configuration files that are checked into a source code control system. At no point in the configuration of any appliance do I touch the management UI – it simply isn’t needed.

How do I automate?

IBM’s interface to the appliance is the documented on-the-wire REST API’s. This means that the composition of a client that calls the API’s via HTTP is up to you. Personally, I write mine in Java and leverage the Apache Commons HTTP client. This is simply a development language preference, and probably not the most efficient or popular method. The majority of people I talk to prefer to implement in Python due to it’s rich scripting capabilities. Ultimately the choice is yours, but I do have hopes of publishing an example in this space in Python soon, so stay tuned for that.

For now, I want to at least share the most common API’s that I use, and how to call them with curl. This will at least show you how to get started, regardless of the scripting language you choose. For the examples in this article, consider an appliance using ISAM 9 that has just been installed with the ISAM 9 ISO, and has had a management IP configured at 192.168.42.101/255.255.255.0.

Finding usage for REST API’s

All of the REST API’s supported by IBM are documented in the Web Services help on the appliance itself. After logging into the local management interface (LMI) with a browser, you can find the web service help via Help -> Web Services, as shown:

An example of the help text for the first API we are going to introduce is shown below:

Alot more information than what you can see in this screenshot is included, including expected and error return codes and data. Now that we know where to look for REST API documentation, let’s see how to use the REST API’s to complete basic tasks. Overall appliance automation is simply a matter of combining and expanding on these automation tasks until an entire end-to-end system is configured.

Determining the ISAM appliance version

Because I’m writing a framework that I hope to work with current and future version of the appliance, I like to know what version I’m working with so that any differences in capability or function between versions can be handled from the same code base. A good example of where I’ve already used this is with the “Deploy Pending Changes” function, which has some slight differences between ISAM 7, 8, and 9. Let’s look at an API for determining the firmware version:

curl -H "Accept: application/json" -k -u "admin:admin" https://192.168.42.101/firmware_settings

After putting the response through a JSON formatter:

[
  {
    "partition": "1 (Active)",
    "last_boot": "1447618784",
    "name": "isam_9.0.0.0_20151015-2250",
    "active": true,
    "comment": "",
    "id": 1,
    "firmware_version": "IBM Security Access Manager 9.0.0.0",
    "install_date": "1447596877",
    "backup_date": null,
    "install_type": "ISO"
  },
  {
    "partition": "2",
    "last_boot": "Never",
    "name": "isam_9.0.0.0_20151015-2250",
    "active": false,
    "comment": "",
    "id": 2,
    "firmware_version": "IBM Security Access Manager 9.0.0.0",
    "install_date": "1447596892",
    "backup_date": null,
    "install_type": "ISO"
  }
]

Take note of the (Active) partition, and you can determine the appliance version from the “firmware_version” field. Note that for the rest of this article we’ll assume we are working with ISAM 9, however if you are dealing with multiple versions of the appliances and need to perform slightly different commands for each, this is the field that I would use to determine what I’m working with.

Changing the admin password

By default when a new appliance is installed, the admin user password is just admin. Let’s show how to change it to Passw0rd instead. The help text for this API can be found in the Web Services help under Manage: System Settings -> System Settings -> Administrator Settings -> Updating the administrator settings.

curl -H "Accept: application/json" -k -u "admin:admin" -X PUT -d '{"oldPassword":"admin","newPassword":"Passw0rd","confirmPassword":"Passw0rd","sessionTimeout":30}' https://192.168.42.101/admin_cfg

At this point the admin password will be changed, and any further REST API calls will required the new password is the basic-auth header. The sessionTimeout is defaulted to 30, and you can see this value by first performing a GET on the same URL, so in this case we are just keeping it the same.

Configuring a DNS server

In this simple example we will show how to config a single DNS server to 192.168.42.2. The reason I am demonstrating this API in this article is that after DNS is configured, it will be necessary to deploy pending changes, and that function is something I also want to explain.

curl -H "Accept: application/json" -k -u "admin:Passw0rd" -X PUT -d '{"auto":false,"primaryServer":"192.168.42.2"}' https://192.168.42.101/net/dns

After calling the above API, the DNS server is configured into “pending changes”, which needs to be deployed. Let’s look at that process now, which is very commonly used after many configuration operations.

Viewing and deploying pending changes

First, let’s check if there are any pending changes. This should be done after any collection of like operations:

curl -H "Accept: application/json" -k -u "admin:Passw0rd" https://192.168.42.101/isam/pending_changes

{
  "changes": [
    {
      "policyName": "gw_net1_1_0.xml",
      "displayKey": "gw_net.display_name",
      "dateString": "2015/11/16 06:42:56",
      "owner": "admin",
      "ui_page": "../net"
    }
  ]
}

Node that the precense of any element in the “changes” array means that there are pending changes ready to deploy – let’s deploy them now. Note that the only difference between showing pending changes and deploying them is that the deploy operation is a HTTP PUT rather than a GET:

curl -H "Accept: application/json" -k -u "admin:Passw0rd" -X PUT https://192.168.42.101/isam/pending_changes

On success this returns a HTTP response code of 200, plus JSON body text similar to:

{
  "result": 0,
  "message": "Successfully deployed all pending changes.",
  "status": 0
}

Depending on the nature of the change, there may be more for you to do. For example updates to a WebSEAL configuration file will require that WebSEAL server to be restarted. The response codes and text will advise you as to any further obligations to make the change effective. The Web Services help documentation explains more about this.

Tips and Tricks for automation

It will very quickly become apparent as you start investigating and writing code for automating appliance configuration that there are common operations (like managing the deploy changes process) that you repeat a lot. These need to be built into a utility function that can be called in a scripted manner. This is the real reason that languages like Python or even Java need to be used when building an overall automatic configuration strategy. You can’t get away with just curl and bash except for the most trivial of operations. It does take a fair effort to get automation started in your business, but the effort pays itself back in confidence in repeatable deployments, and ability to maintain and scale out your deployment very quickly.

Once you do get started though, pretty much everything can be scripted and automated. In my environments, for example, I script all of the following types of configuration:

• Change of administrator password
• Installation of fixpacks
• DNS
• Static routes and application interfaces
• Default gateway
• Offering activation (which appliance features to activate based on activation codes)
• NTP and Date/Time settings
• Hosts file entries
• Keystores and certificates, both for SSL and LTPA
• ISAM runtime configuration, including policy servers, or base runtime.
• WebSEAL instance creation and configuration, including any configuration file settings
• WebSEAL template page customization
• Configuration of junctions, ACL/POP policy, HTTP transformation rules
• Federation creation, including mapping rules, federations and partners
• Trust Server template and chain creation, including all configuration for STS chains

There are many other things I could configure via automation also (such as advanced access control and OAuth), but I just haven’t had to yet, so haven’t added them to my toolkit.

Advice to ISAM Customers

I cannot stress enough how important it is for you to work on automating configuration and change management and make automated execution for inital setup, change control, and maintenance a part of a new standardized devops process. This will no doubt require reassignment of responsibilities in some parts of your business. Change is inevitable as the digital revolution continues, and the longer you leave it, the further behind you will fall. I expect our services teams and business partners to fill in some of the technical tools and practices required to make this a reality, but ultimately you as the customer need to drive automated development operations into your business processes. As a vendor, IBM will continue to look at the IT landscape and try to deliver products and solutions that make automated deployment possible, resulting in lower total cost of ownership and faster time to value.

As always I welcome your feedback and look forward to helping out with more tips for adoption of ISAM in coming articles!