WHOAMI – API enabled describe service for the Enterprise – Part 2

September 2, 2016

Darin Deters, Architect, Kovarus

This is the second installment of my two-part blog post “WHOAMI – API enabled describe service for the Enterprise”.  In part one I focused on the problem statement and a solution summary. In part two, I will dive into the technical details of WHOAMI and how you can set it up in your environment.

Technology Stack Overview

Platforms

  • ServiceNow – Enterprise CMDB
  • Webhost –  Win2k12r2 IIS with ARR – API proxy

Tools/Clients

  • PowerShell v3 or v4
  • Puppet
  • Wget
  • Curl
  • Bginfo
  • Modern Web browser

Requirement Details

ServiceNow – Service account that is a member of the rest_service role and configured with ‘Web service access only’ as shown in the screenshot below.

servicenow api enabled

Webhost – For our proxy API webhost, we used Windows 2012 R2 with IIS and ARR. If you prefer, other web proxy platforms can be used instead of IIS.

  1. If you haven’t already done so, add the Web Server role to your Windows server.
  2. Download and install Application Request Routing/ARR. ARR adds reverse proxy functionality to IIS.

Configuration details

We need a few components in place to connect the dots between WHOAMI. To get started, we need to base64 encode our service account credentials. After we encode the service account credentials we will walk through the webhost configuration details and lastly setting up DNS.

Credential Encoding walkthrough

  1. Browse to BASE64 decode and encode
  2. Click on the encode tab
  3. Paste in the service account credentials in the format of username:password and click encode. (generic credential have been provided)

base64 api enabled

Webhost setup walkthrough 

In order to configure ARR as a proxy to ServiceNow we need to know three important artifacts:

  • Our ServiceNow instance name (ex: https://myinstance.service-now.com)
  • The ServiceNow service account credentials
  • The cmdb database fields that you want to display. In our example we will be querying the following fields: cpu_count,cpu_core_count,cpu_speed,os, and used_for.

ARR has a GUI interface that writes the configuration details to web.config into the root directory of the website or sub directory (depending on your selection). In our demo, we are setting up the entire site for WHOAMI so therefore the web.config file will be stored in the root directory of the WHOAMI site. I’ll leave it up to you if you are more comfortable to work in the GUI or in a text editor to create the arr web.config file.

The screenshot below was taken from my lab environment and can be used as a reference for your environment.

I would like to address a few key elements that can be found in the configuration file.

  • ip_address={REMOTE_ADDR} – This URL parameter is essential. When your client/ci connects to the proxy API service we need a known fact about your configuration item that can be used to find the correct record in the CMDB. The IP address provides a unique value that we can pretty much guarantee to be the best source of truth.
  • HTTP_ACCEPT and CONTENT_TYPE – These server variables ensure that we are returning the data in JSON format
  • HTTP_Authorization – The value for this particular server variable is the encoded service account credentials. The syntax for this value is as follows “Basic my3c0d3dv@lu3” (encoded value). Refer to the credential encoding walk through for more information.

dns_config

DNS configuration

When setting up WHOAMI in your environment, make sure and create a DNS record that points to the webhost. Depending on your configuration this may consist of an A record or CNAME that points back to the host A record.

WHOAMI Architecture Overview Diagram

whoami_diagram

Testing WHOAMI

Testing the WHOAMI service is straightforward and easy! Simply point your favorite tool or client application at the DNS record that was created for WHOAMI!

Test case #1: PowerShell test results from Windows Server

testcase1

Test case #2: Curl test results from Linux

testcase2

Test case #3: Powershell detailed test results (only selecting used_for field)

testcase3

Final Thoughts

WHOAMI helps bridge the divide between the virtual datacenter and enterprise CMDB. The foundation of WHOAMI can be integrated with multiple platforms and tools. From an enablement perspective, WHOAMI is a self-service solution that unleashes the enterprise.

Transformation is key to your cloud journey. I encourage you to continue to think outside of the box, harness creative solutions like WHOAMI and unleash your business and employees!

If you need or would like to know more, please do not hesitate to contact us!