This is part three 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 four is Managing OpenSSO Entitlements Using REST.

With the upcoming release of OpenSSO Express 9, REST interfaces in the form of URLs have been developed to evaluate policies and return decisions from the Entitlements Service. All of the policy evaluation interfaces support HTTP GET and POST actions, and some of them return JavaScript Object Notation (JSON) objects.

The policy evaluation URLs begin with the base which is 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 policy evaluation URL is:

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

The available policy evaluation interfaces (which replace OpenSSO-REST-string in the URL) are decision, entitlement, decisions, and entitlements. 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.

Evaluating a Decision for One Resource

The decision interface returns a plain text string of deny or allow in regards to a request for access. The URL may be populated with the following information.
  • subject defines the requesting user using the URL encoded value of the encoded token.id.
  • action defines the action to be evaluated.
  • application defines the requested service. This is an optional parameter and the default value is iPlanetAMWebAgentService.
  • resource defines the resource to be evaluated.
  • env defines an optional environment map. This map may contain information such as the date and time or the IP address of the client. There is no default parameter. Accepted values include:
    1. requestDnsName – The value would be a set of strings representing the DNS names of the client from which the user is making the request in the form ccc.ccc.ccc. If the env parameter is null or does not define a requestDnsName value, the value is obtained from the user’s SSOToken.
    2. requestIp – The value would be a string representation of the IP address of the client from which the user is making the request in the form n.n.n.n where n is a value between 0 and 255, inclusive; for example, env=requestIp%3D125.12.133.1.
    3. requestTime – For example, env=requestTime%3D1248994000000.
    4. requestTimeZone – The value would be a Java TimeZone object; for example, an abbreviation such as PST, a full name such as America/Los_Angeles or a custom ID such as GMT-8:00. See the TimeZone Java API Reference for more information.

For example: 

http://www.example.com:8080/opensso/ws/1/entitlement/decision?
subject=vd6RXuEnYJl93VWftk9plOzAqfQ%3D
&action=GET
&application=iPlanetAMWebAgentService
&resource=http://www.example.com:80/index.html
&env=requestIp%3D125.12.122.4

This example REST call might return a plain text allow if the subject has permission to access http://www.example.com:80/index.html with GET method and client IP address 125.12.122.4.


Evaluating a Decision and Returning Additional Information for One Resource

The entitlement interface returns a list of JSONEntitlement objects in regards to a request for access. Although similar to the decision interface, it allows more information to be returned. The URL may be populated with the following information.
  • subject defines the requesting user using the URL encoded value of the encoded token.id.
  • application defines the requested service. This is an optional parameter and the default value is iPlanetAMWebAgentService.
  • resource defines the resource to be evaluated.
  • env defines an optional environment map. This map may contain information such as the date and time or the IP address of the client. There is no default parameter. Accepted values include:
    1. requestDnsName – The value would be a set of strings representing the DNS names of the client from which the user is making the request in the form ccc.ccc.ccc. If the env parameter is null or does not define a requestDnsName value, the value is obtained from the user’s SSOToken.
    2. requestIp – The value would be a string representation of the IP address of the client from which the user is making the request in the form n.n.n.n where n is a value between 0 and 255, inclusive; for example, env=requestIp%3D125.12.133.1.
    3. requestTime – For example, env=requestTime%3D1248994000000.
    4. requestTimeZone – The value would be a Java TimeZone object; for example, an abbreviation such as PST, a full name such as America/Los_Angeles or a custom ID such as GMT-8:00. See the TimeZone Java API Reference for more information.

For example: 

http://www.example.com:8080/opensso/ws/1/entitlement/entitlement?
subject=vd6RXuEnYJl93VWftk9plOzAqfQ%3D
&application=iPlanetAMWebAgentService
&resource=http://www.example.com:80/index.html
&env=requestIp%3D125.12.122.4

In the following result for this example, statusCode":200 signifies that the REST call has succeeded. Additionally, the policy evaluation confirms that the subject has permission to access http://www.anotherexample.com:80/index.html using the GET method from the client IP address 125.12.122.4. 

{
"statusCode":200,
"statusMessage":"OK"
"body":{
"actionsValues":{"GET":true},
"attributes":{},
"advices":{},
"resourceName":"http://www.anotherexample.com:80/index.html"
}
}


Evaluating a Decision for Multiple Resources

The decisions interface returns a list in the form of a JSONEntitlements object in regards to a request for access to a set of resources. The URL may be populated with the following information.
  • subject defines the requesting user using the URL encoded value of the encoded token.id.
  • application defines the requested service. This is an optional parameter and the default value is iPlanetAMWebAgentService.
  • resources defines the set of resources to be evaluated. More than one resources parameter may be added to the URL.
  • env defines an optional environment map. This map may contain information such as the date and time or the IP address of the client. There is no default parameter. Accepted values include:
    1. requestDnsName – The value would be a set of strings representing the DNS names of the client from which the user is making the request in the form ccc.ccc.ccc. If the env parameter is null or does not define a requestDnsName value, the value is obtained from the user’s SSOToken.
    2. requestIp – The value would be a string representation of the IP address of the client from which the user is making the request in the form n.n.n.n where n is a value between 0 and 255, inclusive; for example, env=requestIp%3D125.12.133.1.
    3. requestTime – For example, env=requestTime%3D1248994000000.
    4. requestTimeZone – The value would be a Java TimeZone object; for example, an abbreviation such as PST, a full name such as America/Los_Angeles or a custom ID such as GMT-8:00. See the TimeZone Java API Reference for more information.

For example: 

http://www.example.com:8080/opensso/ws/1/entitlement/decisions?
subject=vd6RXuEnYJl93VWftk9plOzAqfQ%3D
&application=iPlanetAMWebAgentService
&resources=http://www.example1.com:80/index.html
&resources=http://www.example2.com:80/index.html
&resources=http://www.example3.com:80/index.html
&env=requestIp%3D125.12.122.4

In the following result for this example, statusCode":200 signifies that the REST call has succeeded. Additionally, the policy evaluation confirms that the subject has permission to access http://www.example2.com:80/index.html using the GET method from the client IP address 125.12.122.4. The subject does not have permission, though, to access http://www.example2.com:80/index.html using the GET method from the client IP address 125.12.122.4 because it does not fall within the specified range defined as a condition of the policy: 128.122.18.1 to 128.122.18.254. No decision has been made for the third resource, http://www.example3.com:80/index.html. 

{
"statusCode":200,
"statusMessage":"OK"
"body":{
"results":[
{
"actionsValues":{"GET":true},
"attributes":{},
"advices":{},
"resourceName":"http://www.example1.com:80/index.html"
}
{
"actionsValues":{"GET":false},
"attributes":{},
"advices":{
"com.sun.identity.entitlement.IPCondition":[
"requestIp=128.122.18.1-128.122.18.254"
]
},
"resourceName":"http://www.example2.com:80/index.html"
}
{
"actionsValues":{},
"attributes":{},
"advices":{},
"resourceName":"http://www.example3.com:80/index.html"
}
]
},
}


Evaluating a Decision for A Root and Sub Tree Resources

The entitlements interface takes a given root resource and provides the decisions for all of its sub resources. It returns a list in the form of a JSONEntitlements object in regards to the request for access. For example, given the root resource of http://www.example.com, results for all sub resources (including http://www.example.com/hr/*, http://www.example.com/eng/* and http://www.example.com/sales/*) will be returned. The URL may be populated with the following information.
  • subject defines the requesting user using the URL encoded value of the encoded token.id.
  • application defines the requested service. This is an optional parameter and the default value is iPlanetAMWebAgentService.
  • resource defines the root of the set of resources to be evaluated.
  • env defines an optional environment map. This map may contain information such as the date and time or the IP address of the client. There is no default parameter. Accepted values include:
    1. requestDnsName – The value would be a set of strings representing the DNS names of the client from which the user is making the request in the form ccc.ccc.ccc. If the env parameter is null or does not define a requestDnsName value, the value is obtained from the user’s SSOToken.
    2. requestIp – The value would be a string representation of the IP address of the client from which the user is making the request in the form n.n.n.n where n is a value between 0 and 255, inclusive; for example, env=requestIp%3D125.12.133.1.
    3. requestTime – For example, env=requestTime%3D1248994000000.
    4. requestTimeZone – The value would be a Java TimeZone object; for example, an abbreviation such as PST, a full name such as America/Los_Angeles or a custom ID such as GMT-8:00. See the TimeZone Java API Reference for more information.
For this example, assume that http://www.examplefour.com:80 has two sub resources: /index.html and /hr/index.html. 

http://www.example.com:8080/opensso/ws/1/entitlement/entitlement?
subject=vd6RXuEnYJl93VWftk9plOzAqfQ%3D
&application=iPlanetAMWebAgentService
&resource=http://www.examplefour.com:80
&env=requestIp%3D125.12.122.4

In the following result statusCode":200 signifies that the REST call has succeeded. Additionally, the policy evaluation confirms that the subject has permission to access http://www.examplefour.com:80/index.html using the GET method from the client IP address 125.12.122.4. The subject does not have permission, though, to access http://www.examplefour.com:80/hr/index.html using the GET method from the client IP address 125.12.122.4 because it does not fall within the specified range defined as a condition of the policy: 128.122.18.1 to 128.122.18.254. 

{
"statusCode":200,
"statusMessage":"OK"
"body":{
"results":[
{
"actionsValues":{},
"attributes":{},
"advices":{},
"resourceName":"http://www.anotherexample.com:80"
}
{
"actionsValues":{"GET":true},
"attributes":{},
"advices":{},
"resourceName":"http://www.anotherexample.com:80/index.html"
}
{
"actionsValues":{"GET":false},
"attributes":{},
"advices":{
"com.sun.identity.entitlement.IPCondition":[
"requestIp=128.122.18.1-128.122.18.254"
]
},
"resourceName":"http://www.anotherexample.com:80/hr/index.html"
}
]
},
}

Be aware though this will not work if you are wicked – as illustrated by Cage the Elephant in their song Ain’t No Rest for the Wicked.

Advertisement