The arguments continue on whether REST is a newer standard or yet another form of RPCs. There is a lot of literature available on the Web to learn more about the RESTful architectures and their design. It is beyond the scope of this book to discuss those architectural aspects of REST. Let us learn how one can invoke the REST interfaces of the OpenSSO server. The beauty of RESTful interfaces is their flexibility and adaptability for a wide range of purposes. These interfaces can be invoked either through a browser or from a high-level language program; it just opens up an HTTP URL connection to the server.
All the REST interfaces require a valid SSO token in order to access them except the authentication. It takes a username and a password parameter to issue a valid SSO token provided the credentials are valid. There are multiple ways to invoke this authentication interface. Typically this interface will be invoked to obtain an SSO token in order to access a resource that is protected by OpenSSO. Let us see some examples on invoking the authenticate interface:
curl -v -d "username=thanga&password=secret" http://opensso.packt-services.net:9090/opensso/identity/authenticate
* About to connect() to opensso.packt-services.net port 9090
* Trying 192.168.1.120... * connected
* Connected to opensso.packt-services.net (192.168.1.120) port 9090
> POST /opensso/identity/authenticate HTTP/1.1
User-Agent: curl/7.12.1 (i386-redhat-linux-gnu) libcurl/7.12.1 OpenSSL/0.9.7a zlib/1.2.1.2 libidn/0.5.6
Host: opensso.packt-services.net:9090
Pragma: no-cache
Accept: */*
Content-Length: 32
Content-Type: application/x-www-form-urlencoded
&username=thanga&password=secret< HTTP/1.1 200 OK
< Server: Apache-Coyote/1.1
< Content-Type: text/plain;charset=UTF-8
< Content-Length: 72
< Date: Sun, 27 Jun 2010 16:27:24 GMT
token.id=AQIC5wM2LY4SfcxRFMGPbmwEtT9nCukQJSfbnG6lTmIt978.*AAJTSQACMDE.*
* Connection #0 to host opensso.packt-services.net left intact
* Closing connection #0
As you can see, we are trying to authenticate to the server as thanga with credential secret. We have forced the POST method using the -d option to the curl command. This, in turn, produced an access log at the Apache Tomcat server, which looks something like this:
192.168.1.120 - - [27/Jun/2010:09:27:24 -0700] "POST /opensso/identity/authenticate HTTP/1.1" 200 72
So far, so good. No issues. We got the SSO token with the session identifier (returned as token.id). Well, let us use the browser to perform the same authentication operation. Enter http://opensso.packt-services.net:9090/opensso/identity/authenticate?username=thanga&password=secret.
Now let us look at the access log of the container to observe what kind operation is logged:
192.168.1.120 - - [27/Jun/2010:09:40:30 -0700] "GET /opensso/identity/authenticate?username=thanga&password=secret HTTP/1.1" 200 72
Here the browser initiated a HTTP GET operation to obtain the token and the username and password which are logged in plain text in the container's access log file. This is considered a huge security concern and this problem has been addressed in the OpenSSO 8.0 Update 2 commercial version of the product. With that fix, no matter how you invoke, the authenticate interface will only support the POST method. However, this fix is not available in the Express 9 candidate that has been used to generate examples for this book.
Alternatively, the REST authentication interface can be accessed with some of the URL parameters (not all) that we discussed in Chapter 4. The following example shows you how to authenticate to a specific realm with module-based authentication:
curl -d "username=thanga&password=secret&module=ldap&realm=/red" http://opensso.packt-services.net:9090/opensso/identity/authenticate
token.id=AQIC5wM2LY4SfczR0j8j-_4BBvU2QijcYyiU72wX5F4d3Ew.*AAJTSQACMDE.*
In this scenario, the user has been authenticated to the sub realm /red using the LDAP authentication module instance named ldap. You should be cautious about using the parameters, though by design it is expected to work. However, the express build 9 exhibits some buggy behavior in the internal authentication as it does not set a proper realm and module instance in the SSO token.
I am sure you are now familiar with obtaining an SSO token using the authenticate interface. Now let us see how a pre-existing token can be validated using the REST interface. It is very critical for the protected application to validate that the token sent by the client is still valid and has not expired or timed out. This can be easily accomplished by invoking the Boolean method isTokenValid that would return true if the given SSO token is valid.
To invoke the isTokenValid method, you should first have a valid token which can be obtained by using the authenticate method:
curl -d "&username=thanga&password=secret" http://opensso.packt-services.net:9090/opensso/identity/authenticate
token.id=AQIC5wM2LY4SfcyozDeLktwuC73qWK1sggRgYM0jFIUjLhA.*AAJTSQACMDE.*
curl -d "tokenid=AQIC5wM2LY4SfcyozDeLktwuC73qWK1sggRgYM0jFIUjLhA.*AAJTSQACMDE.*" http://opensso.packt-services.net:9090/opensso/identity/isTokenValid
boolean=true
After getting the token, you can apply the isTokenValid method to validate the session token. It will return boolean=true if valid, otherwise boolean=false. There is also another way to supply the tokenid—by using the cookie name. An example of an out of the box cookie name is iPlanetDirectoryPro, so you can supply the cookie name using the -b option to the curl command, as follows:
curl -b "iPlanetDirectoryPro=AQIC5wM2LY4SfcyozDeLktwuC73qWK1sggRgYM0jFIUjLhA.*AAJTSQACMDE.*" http://opensso.packt-services.net:9090/opensso/identity/isTokenValid
boolean=true
This is a GET operation as opposed to POST.
Like the browser there is an interface provided in the REST to invalidate or logout the session. OpenSSO provides the logout interface to destroy a valid session, a generic invalid session. A GeneralFailure Service URL not found exception will be returned upon invoking this method with an invalid session:
curl -d "&username=thanga&password=secret&module=ldap&realm=/red" http://opensso.packt-services.net:9090/opensso/identity/authenticate
token.id=AQIC5wM2LY4SfcyteboiZeMaSJaKP8DFLWxEtecVHXwmPdA.*AAJTSQACMDE.*
curl -d "subjectid=AQIC5wM2LY4SfcyteboiZeMaSJaKP8DFLWxEtecVHXwmPdA. *AAJTSQACMDE.*" http://opensso.packt-services.net:9090/opensso/identity/ logout
The first command is used to get the token for the user identity thanga. Subsequently, it will be destroyed by invoking the logout method with subjectid containing the session handle. The same thing can be achieved by using a GET operation along with the iPlanetDirectoryPro cookie value:
Logging security events is one of the core competencies for the access management products such as OpenSSO. It is possible to create the log events or any logging-related message by invoking the log REST method. Essentially it takes three mandatory parameters in order to perform a server-side logging:
appid:It is the authorization token that has the permission to write to log files. This could be the token oflogadminoramadmin.subjectid:It is the identity subject whose logging event is being written to the log store.logname:It implies the database table or the flat file name that will be created if not existing already. It could be any one of the existing log module names as well, such asamConsole.access.message:It is the actual event name or text that will be written into the log file or DB table.
curl -d "appid=AQIC5wM2LY4Sfcxuwn4vnLgPg20M9RXroNx2zaFdCf91gac.*AAJTSQAC MDE.*&subjectid=AQIC5wM2LY4SfczSeGfek2Tgl8M6dtwgmg4xjSzswKmpNeY.*AAJTSQACMDE. *&logname=CURLdb&message=testmessagefromthecurl" http://opensso.packt-services. net:9090/opensso/identity/log
As you can see, there are two different SSO tokens supplied. One, the identity whose events are being logged using the privileged token provided in the appid parameter. The other token provided in the subjectid parameter, this will be user to whom the log events are written. The resulting content of the log file (CURLdb) will appear as follows:
#Version: 1.0
#Fields: time Data LoginID ContextID IPAddr LogLevel Domain LoggedBy MessageID ModuleName NameID HostName
"2010-06-27 11:50:02" /export/ssouser/TOMCAT/opensso-9090/opensso/log/ "cn=dsameuser,ou=DSAME Users,dc=opensso,dc=java,dc=net" 4b3c1b92dbed22c501 "Not Available" INFO dc=opensso,dc=java,dc=net "cn=dsameuser,ou=DSAME Users,dc=opensso,dc=java,dc=net" LOG-1 CURLdb "Not Available" 192.168.1.120
"2010-06-27 11:50:02" testmessagefromthecurl id=thanga,ou=user,dc=opensso,dc=java,dc=net 4b7c4ee68a30a02b01 "Not Available" INFO dc=opensso,dc=java,dc=net id=amadmin,ou=user,dc=opensso,dc=java,dc=net "Not Available" CURLdb "Not Available" 192.168.1.120
Authorization is one of the most frequently invoked interfaces in the access management security arena. OpenSSO does provide a Boolean method that would yield true or false for a given resource URI. To test this interface, apparently you must set up a policy for the URI used in the authorize method. It takes three mandatory parameters:
Assuming the policies are set up (refer to Chapter 6) appropriately, here is the sample command to invoke the authorize method:
curl -d "uri=http://payslip.packt-services.net:7070/index.html&subjectid=AQIC5wM2LY4SfczSeGfek2Tgl8M6dtwgmg4xjSzswKmpNeY.*AAJTSQACMDE.*&action=POST" http://opensso.packt-services.net:9090/opensso/identity/authorize
boolean=false
curl -d "uri=http://payslip.packt-services.net:7070/index.html&subjectid=AQIC5wM2LY4SfczSeGfek2Tgl8M6dtwgmg4xjSzswKmpNeY.*AAJTSQACMDE.*&action=GET" http://opensso.packt-services.net:9090/opensso/identity/authorize boolean=true
The policy rules for the resource URI used will resemble the following screenshot:
