This is the fourth and final part (the end) of a four part series on the OpenSSO REST interfaces for the Entitlements Service. Part one is Authenticating for the OpenSSO Entitlements Service REST Interfaces, part two is Listening for the OpenSSO Entitlements Service Using REST, and part three is Evaluating OpenSSO Entitlements Using REST.

With the upcoming release of OpenSSO Express 9, REST interfaces in the form of URLs have been developed to search, get, add, modify and remove Entitlement Service privileges (policies). The privilege management interfaces support both HTTP GET, PUT, DELETE, and POST actions, and return JavaScript Object Notation (JSON) objects.

The privilege management URLs begin with the base which can be appended with a specific string based on the action desired. One or more parameters are then added based on the information required by the action. The format of the OpenSSO REST privilege management URL is:

http://OSSO-host:OSSO-port/opensso/ws/1/entitlement/privilege/OpenSSO-REST-string?parameter1=value1&parameter2=value2&parameterN=valueN

To search for a privilege or add a new configuration, use the base URL (http://OSSO-host:OSSO-port/opensso/ws/1/entitlement/privilege/), replace OpenSSO-REST-string with the appropriate privilege name, and append the appropriate parameters. If the value of the parameters (value1, value2, …, valueN) contains unsafe characters, they need to be URL encoded when forming the REST URL. For example, an equal sign (=) needs to be replaced with %3D or an ampersand (&) needs to be replaced with %26.

NOTE: Prior to making a call using one of these RESTful interfaces, the subject must authenticate to OpenSSO and get a session token identifier. The SHA1 hashed value of this token.id then needs to be base64 encoded and used as input for these REST URLs. See Authenticating for the OpenSSO Entitlements Service REST Interfaces for more information.

The following sections contain more information.

Searching for Privileges

The privilege interface uses HTTP GET to return a JSON string that lists the configured privileges under a particular realm; by default, the / Top Level Realm is searched. The URL may be populated with the following information.
  • subject defines the requesting user using the URL encoded value of the encoded token.id.
  • filter defines criteria to narrow down the privileges searched. For example, if there are privileges named as a1, a2, b1 and b2, the filter name=a* would narrow the search to privileges that begin with a. The default value is name=*.
For example: 

http://www.example.com:8080/opensso/ws/1/entitlement/privilege?
subject=vd6RXuEnYJl93VWftk9plOzAqfQ%3D
&filter=name%3Da*

This REST call returns a JSON string. The example below means that there is a privilege named example1 under the top level realm. 

{
"statusCode":200,
"statusMessage":"OK",
"body":{
"result":[
"example1"
]
}
}


Adding a New Privilege

The privilege interface also uses HTTP POST to add a JSON representation of the defined privilege to the Entitlement Service under a particular realm; by default, the / Top Level Realm. The URL may be populated with the following information.
  • subject defines the requesting user using the URL encoded value of the encoded token.id.
  • privilege.json defines the privilege configuration as a JSON representation.
For example: 

http://www.example.com:8080/opensso/ws/1/entitlement/privilege?
subject=vd6RXuEnYJl93VWftk9plOzAqfQ%3D
&privilege.json=JSON-representation-of-the-privilege

This second example of the REST call is displayed as it might be in an HTTP message to illustrate the request and response exchange of HTTP POST. 
POST /opensso/ws/1/entitlement/privilege HTTP/1.1
subject=vd6RXuEnYJl93VWftk9plOzAqfQ%3D
&privilege.json=JSON-representation-of-the-privilege

It returns a JSON string representing the outcome of the action. The example below means a successful POST. 
{
"statusCode":201,
"statusMessage":"Created",
"body":"Created"
}


Retrieving a Privilege Configuration

To get the configuration for a specific privilege, append the privilege name and parameter to the end of the URI. The interface uses HTTP GET to return a JSON representation of the defined privilege. The only parameter is the URL encoded value of the encoded token.id that defines the subject. 

http://www.example.com:8080/opensso/ws/1/entitlement/privilege/example1?
subject=vd6RXuEnYJl93VWftk9plOzAqfQ%3D

This REST call returns a JSON representation of privilege example1. The example below means that the subject accessing http://www.example.com must be authenticated. 
{
"statusCode":200,
"statusMessage":"OK",
"body":{
"result":"{
\"name\":\"example1\",
\"description\":\"desciption\",
\"eSubject\":{
\"state\":\"\",
\"className\":\"com.sun.identity.entitlement.AuthenticatedESubject\"
},
\"entitlement\":{
\"name\":\"entitlement\",
\"applicationName\":\"iPlanetAMWebAgentService\",
\"resourceNames\":[
\"http://www.example.com/*\"
]
\"actionsValues\":{
\"GET\":true
},
}
}"
}
}


Modifying an Existing Privilege

To modify the configuration of an existing privilege, append the privilege name and parameters after the URI. The interface uses HTTP PUT to modify the defined privilege based on a JSON representation used as input. The URL may be populated with the following information.
  • The privilege being modified is defined by the OpenSSO-REST-string variable of the URL. In the following example, the privilege being modified is example2.
  • subject defines the requesting user using the URL encoded value of the encoded token.id.
  • privilege.json defines the new privilege configuration as a JSON representation.

http://www.example.com:8080/opensso/ws/1/entitlement/privilege/example2?

subject=vd6RXuEnYJl93VWftk9plOzAqfQ%3D
&privilege.json=JSON-representation-of-the-privilege

This second example of the REST call is displayed as it might be in an HTTP message to illustrate the request and response exchange of HTTP PUT. 

PUT /opensso/ws/1/entitlement/privilege/example2 HTTP/1.1
subject=vd6RXuEnYJl93VWftk9plOzAqfQ%3D
&privilege.json=JSON-representation-of-the-privilege

This REST call returns a JSON string representing the outcome of the action. The example below means a successful PUT. 

{
"statusCode":200,
"statusMessage":"OK",
"body":{
"result":"OK"
}
}


Removing an Existing Privilege

To remove an existing privilege, append the privilege name and parameter after the URI. The interface uses HTTP DELETE to remove the defined privilege. The parameter is the URL encoded value of the encoded token.id that defines the subject. 


http://www.example.com:8080/opensso/ws/1/entitlement/privilege/example2?

subject=vd6RXuEnYJl93VWftk9plOzAqfQ%3D

This second example of the REST call is displayed as it might be in an HTTP message to illustrate the request and response exchange of HTTP DELETE.

DELETE /opensso/ws/1/entitlement/privilege/example1?subject=vd6RXuEnYJl93VWftk9plOzAqfQ%3D HTTP/1.1

This REST call returns a JSON string representing the outcome of the action. The example below means a successful DELETE. 

{
"statusCode":200,
"statusMessage":"OK",
"body":{
"result":"OK"
}
}

I couldn’t decide whether to end this series with The Doors The End or Nancy Sinatra’s The End. While searching around I found that Nancy’s song was being used in a television commercial so here it is (the song not the commerical) with pix of the minx herself.

Advertisement