I have been working on a large-scale integration project for Ariba on Demand at a client site, and while working in varying capacities and roles, have had quite a lot (read – ‘everything’) to do with implementing the single sign-on (SSO) relay provided as-is and unsupported by Ariba. I'm not going into the spiel as to what Ariba on Demand is and how/why its used etc, if your here for Ariba on Demand SSO help, these are high chance you know (I’d hope so!). For the sake of article completeness, but also to contradict the above statement, Ariba on Demand is a cloud-based procurement platform allowing enterprises to run their entire purchasing/invoicing/sourcing/contract mgmt etc workflow in a single application environment.
This article is intended to be supplementary to the provided Ariba documentation on the provided relay code (specifically the IIS-ASP relay) and based on my own experience of trawling through the code and hacking it into place.
The Ariba diagram
The above diagram is supplied by Ariba in the Remote Authentication Kit – Design Overview.doc
It explains the basic flow between the various components to authenticate a user in Ariba. The purpose of this post is not to re-iterate what is shown in the diagram but to dive further down into the workings of the relay for debugging and personal-sanity related reasons.
My Diagram – explains the various query string parameters of each hop
I believe there are two parts of the relay that aren’t well documented or explained. The first being how to encryption / decryption of challenge key works and secondly the details of the values being passed back and forward from the relay to Ariba. This might be stating the obvious for those who have worked with SSO and encryption methods before, but it wasn’t for me and I’m guessing it may be useful for someone else down the line also.
Setting up the relay and how the encryption works
The provided relay is a single page that retrieves the current user, encrypts a key sent from Ariba and sends them both (username and encrypted key) back to Ariba for authentication.
So lets back up a bit here – challenge key? Encryption what?
The keys – Public and Private Keys
I'm not going to get into the detail of public/private key architecture, but the provided solution provides a ‘keys\’ folder which contains two sample keys, public.pem and private.pem, along with a genkeys.bat batch file which will create fresh keys into these files (a compulsory step if not done already).
The private key is the one we hold dearly, and the relay page has a configuration line which directs to the location of that private.pem keyfile. It looks like this:
PrivKey = ConfigPath & "D:\pathto\keyfile\private.pem"
In my case, my integration server’s permissions were locked down too tightly and the application did not have access to read this file, and hence the solution did not work. In my experience, this is the single biggest cause of failure of the relay – not having appropriate permission to access the private key file or a mis-configured path in the above line and someone moves the key during deployment.
So what does the relay page do with the keys?
The query string and it’s parameters
Well to protect the integrity of the transaction and stop hijacked sessions, when the user first enters the Ariba URL they are taken to the Ariba portal, and if SSO is configured for that realm, the user is again bounced back to the SSO relay address configured (see above diagram – Hop #2). During this second hop, a unique challenge key is generated and returned to relay as a query string parameter.
This is shown as &key= in my diagram above.
The relay then retrieves the currently authenticated user (depending on your IIS configuration, but using integrated authentication is the best method) and stores that in another query string parameter &user=
This is the value that Ariba will use to match against a user record and provide access into the application.
The private key is used to encrypt a combination of the user and the challenge key given by Ariba, into a single encrypted value and return that to Ariba. No snooping users can decrypt the contents of that string because they are not in possession of the matching public key. This public key is configured in Ariba in order to decrypt the return values and authenticate the request and its integrity.
The user is then bounced back (3rd and final hop) with these details, &user= and &sig=, containing the current user and encrypted digital signature respectively. Ariba takes verifies the value of &sig= by decrypting it with the value given in the public string.
The encryption process in more detail – an optional dive into what is happening
As hinted in the title, this section is entirely optional and is intended to dive into the process of encrypting / decrypting the username and challenge key – specifically the how and the why and ways of trouble shooting when things don't go so smoothly.
As explained above, the relay page encrypts the combined values of the Ariba-generated challenge key and the username of the logged in user. It does this encryption using the industry standard encryption toolkit, OpenSSL, using the pre-compiled Windows 32 distribution which includes openssl.exe (available here).
A line in the relay page defines the bath to openssl.exe, in a similar manner to the private.pem key file explained above:
OpenSSL= "D:\bin\openssl "
So looking further down into the relay page code, the OpenSSL variable is called twice:
set oExec = WshShell.Exec(OpenSSL & "dgst -sha1 –sign “D:\keyfile\private.pem”)
oExec.StdIn.Write key & username
signature = oExec.StdOut.ReadAll()
Here the openssl.exe binary is called with the parameters “dgst –sha1” encode with a sha1 algorithm and “-sign” using the private key value of “D:\keyfile\private.pem”). It then sends the values of key (ariba generated challenge key) and username (value of currently authenticated user) and returns the encrypted version to the value of “signature'”
The next block then encrypts the value of signature with another call to OpenSSL (so another call of openssl.exe) with the parameters of " enc -base64") to encode it into base64. This value is then stored into the variable “sigEncode”.
Finally this value, sigEncode returned to Ariba as a query string (value of &sig=” “), where Ariba uses the SSO configuration value stored for the realm’s public key.
Testing the process – the provided test pages
Fortunately Ariba have provided to test simulation pages in the \LoginTest\ folder to simulate both sides of the Ariba handshake. Providing the configuration values for authURI, OpenSSL and PubKey are correct in both login.asp and login_verify.asp, these pages can be utilised to simulate Ariba connections without having the configure SSO options within Ariba. This proves a useful mechanism that the relay page is functioning as intended before touching production settings.
Hopefully some of the above content was useful, if nothing else it provides a useful reference of my own learnings if I ever need to deploy the relay page again!