Thursday Jan 14, 2010

Evaluating OpenSSO Entitlements Using REST

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.

Wednesday Jan 13, 2010

Listening for the OpenSSO Entitlements Service Using REST

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

There are RESTful management interfaces that can be used to get, add and remove listeners which send notifications to the Entitlements Service when privileges are added, removed, or modified. The listener management interfaces support HTTP GET, DELETE, and POST actions, and returns a JavaScript Object Notation (JSON) object.

The listener management URLs begin with the base which is appended with the encoded URL of the listener. One or more parameters are then added based on the information required by the action. The format of the OpenSSO REST listener management URL is:

http://OSSO-host:OSSO-port/opensso/ws/1/entitlement/listener/encoded-URL?parameter1=value1&parameter2=value2&parameterN=valueN

To get or remove a listener configuration, use the base of the URL (http://OSSO-host:OSSO-port/opensso/ws/1/entitlement/listener/) and replace encoded-URL with the appropriate listener URL. To add a new listener, append the base URL with 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.

Adding a Listener

This interface uses HTTP POST to add the listener configuration for the specified resource. The URL may be populated with the following information.
  • url defines the URL of the listener.
  • subject defines the requesting user using the URL encoded value of the encoded token.id.
  • application defines the generic resource type. See The Entitlements Service In OpenSSO Express 8 for more information.
  • resources defines one or more resources for which the listener is configured.
For example:

http://www.example.com:8080/opensso/ws/1/entitlement/listener?
url=http%3A%2F%2Fwww.listenerexample.com%2Fnotification
&subject=vd6RXuEnYJl93VWftk9plOzAqfQ%3D
&resources=http://www.example1.com/\*

This REST call returns a JSON object affirming the successful addition of the listener.
{
   "statusCode":201,
   "statusMessage":"Created",
   "body":"Created"
}

Retrieving a Listener

This interface uses HTTP GET to return a JSON representation of the specified listener configuration. The URL may be populated with the following information.
  • encoded-URL is appended to the end of the REST URL (before the parameters) and is the encoded URL of the listener.
  • subject defines the requesting user using the URL encoded value of the encoded token.id.
For example:

http://www.example.com:8080/opensso/ws/1/entitlement/listener/
http%3A%2F%2Fwww.listenerexample.com%2Fnotification
&subject=vd6RXuEnYJl93VWftk9plOzAqfQ%3D

This REST call returns a JSON representation of the listener. The example below means that there is a listener for all privileges regarding _http://www.example1.com_.
{
   "statusCode":200,
   "statusMessage":"OK",
   "body":{
        "mapAppToRes":{
             "iPlanetAMWebAgentService":[
                  "http://www.example1.com/\*"
             ]
        },
        "url":"http://www.listenerresttest.com/notification"
   }
}

Removing a Listener

This interface uses HTTP DELETE to remove the specified listener. The URL may be populated with the following information.
  • encoded-URL is appended to the end of the REST URL (before the parameters) and is the URL of the listener.
  • subject defines the requesting user using the URL encoded value of the encoded token.id.
For example:

http://www.example.com:8080/opensso/ws/1/entitlement/listener/
http%3A%2F%2Fwww.listenerexample.com%2Fnotification
&subject=vd6RXuEnYJl93VWftk9plOzAqfQ%3D

This REST call returns a JSON object affirming the successful removal of the listener.

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

And while we're listening, here's Pseudo Echo with their 1981 Aussie hit, Listening.

Tuesday Jan 12, 2010

Authenticating for the OpenSSO Entitlements Service REST Interfaces

This is part one of a four part series on the OpenSSO REST interfaces for the Entitlements Service. Part two is Listening for the OpenSSO Entitlements Service Using REST, part three is Evaluating OpenSSO Entitlements Using REST, and part four is Managing OpenSSO Entitlements Using REST.

The OpenSSO Entitlements Service provides fine grained access control. With the upcoming release of OpenSSO Express 9, RESTful interfaces (in the form of URLs) have been developed for the Entitlements Service. (Information on other OpenSSO RESTful interfaces can be found .)

Before using the Entitlements Service REST interfaces, the user making the calls needs to be authenticated and receive a session token identifier. Following authentication, this identifier must be hashed and encoded for input as a parameter value of the Entitlements Service REST URLs. The following sections have more information.

Authenticating to OpenSSO Before Using REST

Before making a REST call using one of the Entitlements Service URLs, the subject must authenticate to OpenSSO using the authenticate REST identity interface. This identity call, if successful, will get a session token identifier for the subject that will then be used as input for the Entitlements Service REST URLs. An example of the authenticate REST URL is:

http://www.example.com:8080/opensso/identity/authenticate?username=user1&password=changeme

NOTE: For this use, the authenticate URL should use HTTP POST because (the default) HTTP GET logs the user information which might be a security issue in some deployments.

This authenticate call would return a session token.id; for example:

token.id=AQIC5wM2LY4Sfcy9rURsXTOXiNjG2VNFgjtPB6Cw1ICTIK4=@AAJTSQACMDE=#

This session token.id needs to be set as the iPlanetDirectoryPro cookie.

iPlanetDirectoryPro=AQIC5wM2LY4Sfcy9rURsXTOXiNjG2VNFgjtPB6Cw1ICTIK4=@AAJTSQACMDE=#

Additionally, a SHA1-hashed and base64 encoded string needs to be generated from the value of the token.id. This encoded string, representing the user, will be passed as a parameter with every REST call.

Encoding the token.id

This procedure will generate a SHA1-hashed and base64 encoded string from the session token.id previously returned.
  1. Compile the Encoder.java code found on opensso.dev.java.net.

    javac Encoder.java
  2. Run the compiled Encoder to hash and encode the session token.id.

    java Encoder AQIC5wM2LY4Sfcy9rURsXTOXiNjG2VNFgjtPB6Cw1ICTIK4=@AAJTSQACMDE=

The Encoder returns a string such as vd6RXuEnYJl93VWftk9plOzAqfQ=. This string is a SHA1 hash that is also base64 encoded. It must be passed as a parameter with every REST call to indicate the subject; for example:

subject=vd6RXuEnYJl93VWftk9plOzAqfQ=

The actual information on the Entitlements Service REST interfaces will be forthcoming. (And this entry will make more sense. ;> ) It includes policy evaluation, privilege management and listener management REST interfaces. In the meantime, take the Rest of the Day Off from Neil Finn's 2001 album - Bowie-esque from his Heroes period.


Monday Nov 16, 2009

Make REST Calls from OpenSSO Client SDK on the Video Phone

A new attribute has been added to the Advanced properties to support REST policy calls from the Client SDK to the new Entitlement Service. The com.sun.identity.policy.client.useRESTProtocol property is added to the Advanced -> Custom Properties section of the agent profile with a value of true to enable REST interface calls. If the property is not defined, the value defaults to false. Currently, this property is specific to J2EE agents as web agents do not use REST calls to get policy decisions.

So, yes, I planned to use the new Beyonce song Video Phone (see title) but something about this video (featuring Lady Gaga) is - how shall I say - ridiculous? No music, no melody, no thing - just videeeoooo phone and the same dance moves we've seen in every other Beyonce video. So rather than embedding that trash, here's Annie Golden (of The Shirts and Hair movie) singing Hang Up The Phone. Even in its blurry state this video has more class. And that's the truth.

Tuesday Nov 10, 2009

Those Darlin' OpenSSO REST Policy Evaluation Interfaces

Piggybacking on the information in The OpenSSO REST Interfaces in Black / White, OpenSSO Express 9 will mark the release of the RESTful interfaces for policy evaluation. All of them support both HTTP GET and POST actions, and some of them return JavaScript Object Notation (JSON) objects. The format of the OpenSSO REST URL is:

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

NOTE: 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.

The following sections contain information on invoking the available OpenSSO REST policy evaluation interfaces.

Evaluating a Decision for One Resource

The decision RESTful policy evaluation 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.

  • realm defines the realm in which the subject is defined. This is an optional parameter and the default value is /.
  • subject defines the value of the Universal ID attribute in the requesting user's OpenSSO profile.
  • action defines the action to be evaluated.
  • resource defines the resource to be evaluated.
  • application defines the requested service. This is an optional parameter and the default value is iPlanetAMWebAgentService.
  • env defines an optional environment map. This map may contain information such as the date and time or the IP address of the client. Examples might be env=requestIp%3D125.12.133.1 or env=requestTime%3D1248994000000.

For example:

http://OpenSSO-host:OpenSSO-port/opensso/ws/1/entitlement/decision?action=GET&resource=http://www.example.com/index.html&application=iPlanetAMWebAgentService&subject=uid=demo,ou=user,dc=opensso,dc=java,dc=net&env=requestTime%3D1248994000000

Evaluating a More Specific Decision for One Resource

The entitlement RESTful policy evaluation interface returns a list of JSONEntitlement objects in regards to a request for access to a resource. Although similar to the decision interface, it does allow more information to be returned as a JSON privilege object. The URL may be populated with the following information.

  • realm defines the realm in which the subject is defined. This is an optional parameter and the default value is /.
  • subject defines the value of the Universal ID attribute in the requesting user's OpenSSO profile.
  • resource defines the resource to be evaluated.
  • application defines the requested service. This is an optional parameter and the default value is iPlanetAMWebAgentService.
  • env defines an optional environment map. This map may contain information such as the date and time or the IP address of the client. Examples might be env=requestIp%3D125.12.133.1 or env=requestTime%3D1248994000000.

For example:

http://OpenSSO-host:OpenSSO-port/opensso/ws/1/entitlement/entitlement?resource=http://www.example.com&application=iPlanetAMWebAgentService&subject=uid%3Ddemo,ou%3Duser,dc%3Dopensso,dc%3Djava,dc%3Dnet

The following result signifies that the evaluation has approved the request for access. But, demo does not have access permission to http://www.example.com because the IP address does not fall within the range of 192.122.18.1 and 192.122.18.254.
{
   "statusCode":200,
   "statusMessage":"OK",
   "body":{
       "results":[
       {
          "actionsValues":{
          },
          "attributes":{},
          "advices":{
               "com.sun.identity.entitlement.IPCondition": "[
                    \\"requestIp=192.122.18.1-192.122.18.254\\"
               ]"
          },
          "resourceName":"http://www.example.com"
       }
   }
}

Evaluating a Decision for Multiple Resources

The decisions RESTful policy evaluation 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.

  • realm defines the realm in which the subject is defined. This is an optional parameter and the default value is /.
  • subject defines the value of the Universal ID attribute in the requesting user's OpenSSO profile.
  • resources defines the set of resources to be evaluated. More than one resources parameter may be added to the URL.
  • application defines the (application or application type). This is an optional parameter and the default value is iPlanetAMWebAgentService.
  • env defines an optional environment map. This map may contain information such as the date and time or the IP address of the client. Examples might be env=requestIp%3D125.12.133.1 or env=requestTime%3D1248994000000.

For example:

http://OpenSSO-host:OpenSSO-port/opensso/ws/1/entitlement/decision?resources=http%3A//www.example.com/index.html&resources=http%3A//www.example2.com/index.html&application=iPlanetAMWebAgentService&subject=uid%3Ddemo,ou%3Duser,dc%3Dopensso,dc%3Djava,dc%3Dnet

The following result signifies that the evaluation has approved the request for access. Additionally, demo (the OpenSSO demo user) has POST and GET permission for http://www.example.com and GET permission for http://www.example2.com.
{
   "statusCode":200,
   "statusMessage":"OK",
   "body":{
       "results":[
       {
          "actionsValues":{
             "POST":true,
             "GET":true
          },
          "attributes":{},
          "advices":{},
          "resourceName":"http://www.example.com"
       }
       {
          "actionsValues":{
             "GET":true
          },
          "attributes":{},
          "advices":{},
          "resourceName":"http://www.example2.com"
       }
       ]
   }
}

Evaluating a Decision for A Root and Sub Tree Resources

The entitlements RESTful policy evaluation interface returns a list in the form of a JSONEntitlements object in regards to a request for access to root resource and its (multiple) sub resources. 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.

  • realm defines the realm in which the subject is defined. This is an optional parameter and the default value is /.
  • subject defines the value of the Universal ID attribute in the requesting user's OpenSSO profile.
  • resource defines the root of the set of resources to be evaluated.
  • application defines the requested service. This is an optional parameter and the default value is iPlanetAMWebAgentService.
  • env defines an optional environment map. This map may contain information such as the date and time or the IP address of the client. Examples might be env=requestIp%3D125.12.133.1 or env=requestTime%3D1248994000000.

For example:

http://OpenSSO-host:OpenSSO-port/opensso/ws/1/entitlement/entitlement?resources=http://www.example.com&application=iPlanetAMWebAgentService&subject=uid=demo,ou=user,dc=opensso,dc=java,dc=net&env=requestTime%3D1248994000000

The following result signifies that the evaluation has approved the request for access. But, demo (the OpenSSO demo user) has POST and GET permission only for http://www.example.com/hr/\* and http://www.example.com/engr/\*.
{
   "statusCode":200,
   "statusMessage":"OK",
   "body":{
       "results":[
       {
          "actionsValues":{
          },
          "attributes":{},
          "advices":{},
          "resourceName":"http://www.example.com"
       }
       {
          "actionsValues":{
             "POST":true
             "GET":true
          },
          "attributes":{},
          "advices":{},
          "resourceName":"http://www.example.com/hr/\*"
       }
       {
          "actionsValues":{
             "POST":true
             "GET":true
          },
          "attributes":{},
          "advices":{},
          "resourceName":"http://www.example.com/engr/\*"
       }
       {
          "actionsValues":{
          },
          "attributes":{},
          "advices":{
               "com.sun.identity.entitlement.IPCondition": "[
                    \\"requestIp=192.122.18.1-192.122.18.254\\"
               ]"
          },
          "resourceName":"http://www.example.com/sales/\*"
       }
   }
}

Now enjoy the musical and illustrative (?) accomplishments of Those Darlins with Red Light Love. It's dope. And that's a good thing!

Thursday Oct 08, 2009

The OpenSSO REST Interfaces in Black / White

A RESTful web service assumes all components are exposed using the same, uniform application interface. (An interesting article on other requirements of REST can be read here.) From this high-level HTTP accomplishes this uniformity with its methods such as GET and POST. Thus calling a RESTful web service requires the simple construction of a URL.

OpenSSO exposes a number of interfaces that support a REST architecture. These operations are supported out of the box so no special configurations are required. The format of the URL is:

http://OpenSSO-host:OpenSSO-port/opensso/identity/OpenSSO-REST-interface?parameter1=value1&parameter2=value2&parameterN=valueN

NOTE: 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.

The following sections contain information on invoking the available OpenSSO REST interfaces.

Authentication

The authenticate REST interface opens an HTTP connection to authenticate a user with a POST operation. The following URL defines a username and password that will be authenticated at the OpenSSO root realm - by default, / (Top Level Realm).

http://OpenSSO-host:OpenSSO-port/opensso/identity/authenticate?username=jning&password=pwjning

You can also add the optional uri parameter to the URL. The value of this parameter would be one or more of the URL parameters documented in Accessing the OpenSSO Enterprise Authentication Service User Interface with a Login URL. For example, the following URL will authenticate the user to a specific sub realm.

http://OpenSSO-host:OpenSSO-port/opensso/identity/authenticate?username=jning&password=pwjning&uri=realm=sub_realm_name

You can define additional parameters. For example, the following URL will authenticate the user to a specific sub realm using the specified authentication chain (ldapService, for example).

http://OpenSSO-host:OpenSSO-port/opensso/identity/authenticate?username=jning&password=pwjning&uri=realm=sub_realm_name&service=ldapService

After successful authentication, a token string is returned to represent the authenticated user for other REST operations. Various exceptions might also be thrown such as UserNotFound and InvalidPassword. A generic exception is provided if unable to reach OpenSSO or for other fatal errors.

NOTE: The token string returned is also applied as the value of the subjectid in some OpenSSO REST operations like logout and authorize.

Token Validation

The isTokenValid REST interface validates the token using the POST operation. The following URL defines a tokenid that will be validated by OpenSSO.

http://OpenSSO-host:OpenSSO-port/opensso/identity/isTokenValid?tokenid=AQIC5wM2LY4SfczeSHZ5cHJMmQYU3f5imB2fBBTpkCXADS0=-AT-AAJTSQACMDE=#

The operation returns a value of true or false.

Logout

The logout REST interface validates the token using the POST operation. The following URL defines a tokenid that will be validated by OpenSSO.

http://OpenSSO-host:OpenSSO-port/opensso/identity/logout?subjectid=AQIC5wM2LY4SfczeSHZ5cHJMmQYU3f5imB2fBBTpkCXADS0=-AT-AAJTSQACMDE=#

The operation invalidates the tokenid and logs the user out.

Authorization

The authorize REST interface will verify against created policies that the user is authorized to perform a particular operation (GET or POST) on a particular HTTP resource. The following URL defines a user (subjectid) that wants to POST (action) to the specified resource (uri).

http://OpenSSO-host:OpenSSO-port/opensso/identity/authorize?uri=http://www.sun.com:90&action=POST&subjectid=AQIC5wM2LY4SfczeSHZ5cHJMmQYU3f5imB2fBBTpkCXADS0=@AAJTSQACMDE=#

The operation returns a value of true or false. If the user is not authorized, an exception is thrown. Assuming a policy has been created to allow authenticated users to POST to the defined resource (in this case, http://www.sun.com:90), the above URL would return true.

Logging

The log REST interface will log to the OpenSSO Logging Service. The URL needs to be populated with the following information.
  • appid defines the tokenid of the user with the necessary permissions to write to the log; for example amadmin.
  • subjectid defines the tokenid of the user about whom the log record is being written.
  • logname is the module name of the OpenSSO component invoking the Logging Service; for example, amAuthentication.
  • message is the data being logged.

An example URL is:

http://OpenSSO-host:OpenSSO-port/opensso/identity/log?appid=AQIC5wM2LY4Sfcz24GvZCdv6ie9dTJBa3Co7Rn2QUjKCDuM=@AAJTSQACMDE=#&subjectid=AQIC5wM2LY4SfcwTCcRKSDXEsiJXt71PDAUmN1bm/draPZI=@AAJTSQACMDE=#&logname=amAuthentication&message=test

Searching Identity Types

The search REST interface will search the configured database for particular identities. The URL needs to be populated with the following information.
  • filter defines a set of criteria that controls what is returned by the operation.
  • attributes_name defines one or more LDAP attributes for which to search.
  • attribute_values_value-of-attributes_name defines the value of the attribute (defined by attributes_name) that is being searched.
  • admin defines the tokenid of the user with the necessary permissions to search; for example amadmin.

The following URL would return the available agent types; by default string=wsc, string=wsp, and string=SecurityTokenService.

http://OpenSSO-host:OpenSSO-port/opensso/identity/search?filter=\*&attributes_names=objecttype&attributes_values_objecttype=agent&admin=AQIC5wM2LY4SfcxCWBCNON1gTsaMaHISbYmTyYosv8pCPVw=@AAJTSQACMDE=#

This example would return all user entries.

http://OpenSSO-host:OpenSSO-port/opensso/identity/search?filter=\*&attributes_names=objectclass&attributes_values_objectclass=person&admin=AQIC5wM2LY4SfcxCWBCNON1gTsaMaHISbYmTyYosv8pCPVw=@AAJTSQACMDE=#

Display Identity Data

The attributes REST interface will search the configured database for identity information about the defined subjectid. It retrieves roles and common attributes (including first name and last name) and is used by applications to obtain a user's profile for application-controlled authorization. Optionally, the URL can take one or more attribute_names parameters to define which attribute values will be returned; if attribute_names is not defined it would return all the attributes in the profile. This is an example URL that would return the specified user's LDAP profile.

http://OpenSSO-host:OpenSSO-port/opensso/identity/attributes?attributes_names=uid&subjectid=AQIC5wM2LY4Sfcz6eH4abOQ0el7pnDqmOn6nnn1nrcuE8/w=@AAJTSQACMDE=#

The URL might return something like this:
userdetails.token.id=AQIC5wM2LY4Sfcz6eH4abOQ0el7pnDqmOn6nnn1nrcuE8/w=@AAJTSQACMDE=#
userdetails.attribute.name=sn
userdetails.attribute.value=jning
userdetails.attribute.name=cn
userdetails.attribute.value=jning
userdetails.attribute.name=objectclass
userdetails.attribute.value=sunFederationManagerDataStore
userdetails.attribute.value=top
userdetails.attribute.value=iplanet-am-managed-person
userdetails.attribute.value=iplanet-am-user-service
userdetails.attribute.value=organizationalperson
userdetails.attribute.value=inetadmin
userdetails.attribute.value=iPlanetPreferences
userdetails.attribute.value=person
userdetails.attribute.value=inetuser
userdetails.attribute.value=sunAMAuthAccountLockout
userdetails.attribute.value=sunIdentityServerLibertyPPService
userdetails.attribute.value=inetorgperson
userdetails.attribute.value=sunFMSAML2NameIdentifier
userdetails.attribute.name=userpassword
userdetails.attribute.value={SSHA}XhiE0RMwO/D7SSQ5fYLrTlFjmbHmYbQkIU43FA==
userdetails.attribute.name=uid
userdetails.attribute.value=jning
userdetails.attribute.name=givenname
userdetails.attribute.value=jning
userdetails.attribute.name=inetuserstatus
userdetails.attribute.value=Active

Display Particular Identity Data

The read REST interface will search the configured database for particular identity information about the LDAP user defined by name. The attributes_names parameter defines one or more LDAP attributes for which to search. This is an example URL that would return the specified user's LDAP profile.

http://OpenSSO-host:OpenSSO-port/opensso/identity/read?name=jning&attributes_names=uid&admin=AQIC5wM2LY4SfcxCWBCNON1gTsaMaHISbYmTyYosv8pCPVw=@AAJTSQACMDE=#

The URL might return something like this:
identitydetails.name=jning
identitydetails.type=user
identitydetails.realm=dc=opensso,dc=java,dc=net
identitydetails.attribute=
identitydetails.attribute.name=uid
identitydetails.attribute.value=jning

Creating Identity Types

The create REST interface will create the defined identity type in the configured data store. The URL needs to be populated with the following information. Note the values for these parameters in the sample URLs below.
  • identity_name defines a easily-readable name for the identity.
  • identity_attribute_names defines one or more LDAP attributes to be created for the identity.
  • identity_attribute_values_value-of-identity_attribute_names defines the value of the attribute (defined by attributes_name) being created.
  • identity_realm defines the realm in which the identity is created.
  • identity_type defines the type of identity being created.
  • admin defines the tokenid of the user with the necessary permissions to create; for example amadmin.

This URL would create a user type. Use the search REST interface to verify its creation.

http://OpenSSO-host:OpenSSO-port/opensso/identity/create?identity_name=rest_user&identity_attribute_names=userpassword&identity_attribute_values_userpassword=secret123&identity_attribute_names=sn&identity_attribute_values_sn=sn_of_rest_user&identity_attribute_names=cn&identity_attribute_values_cn=cn_of_rest_user&identity_realm=/&identity_type=user&admin=AQIC5wM2LY4Sfcwbg2YdVMaYsfEqdxHDMUc47WSLBNTOlrk=@AAJTSQACMDE=#

The following URL would create a web agent profile for Policy Agent 3.0 types. Use the search REST interface to verify its creation.

http://OpenSSO-host:OpenSSO-port/opensso/identity/create?&identity_name=webagent&identity_realm=/&identity_type=AgentOnly&identity_attribute_names=userpassword&identity_attribute_values_userpassword=secret123&identity_attribute_names=AgentType&identity_attribute_values_AgentType=WebAgent&identity_attribute_names=SERVERURL&identity_attribute_values_SERVERURL=http://web-agent-host:web-agent-port/opensso

The following URL would create a J2EE agent profile for Policy Agent 3.0 types. Use the search REST interface to verify its creation.

http://OpenSSO-host:OpenSSO-port/opensso/identity/create?&identity_name=j2eeagent&identity_realm=/&identity_type=AgentOnly&identity_attribute_names=userpassword&identity_attribute_values_userpassword=secret123&identity_attribute_names=AgentType&identity_attribute_values_AgentType=J2EEAgent&identity_attribute_names=SERVERURL&identity_attribute_values_SERVERURL=http://J2EE-agent-host:J2EE-agent-port/opensso&identity_attribute_names=AGENTURL&identity_attribute_values_AGENTURL=http://OpenSSO-host:OpenSSO-port/opensso

The following URL would create a 2.2 agent profile. Use the search REST interface to verify its creation.

http://OpenSSO-host:OpenSSO-port/opensso/identity/create?identity_name=webagent70&identity_attribute_names=userpassword&identity_attribute_values_userpassword=secret123&identity_realm=/&identity_type=Agent&admin=AQIC5wM2LY4Sfcwbg2YdVMaYsfEqdxHDMUc47WSLBNTOlrk=@AAJTSQACMDE=#

Updating Identity Data

The update REST interface will update an identity with the information defined in the URL. The following URL would update the user profile with an email address.

http://OpenSSO-host:OpenSSO-port/opensso/identity/update?identity_name=rest_user&identity_attribute_names=mail&identity_attribute_values_mail=restUser@rest-DOT-org&admin=AQIC5wM2LY4Sfcwbg2YdVMaYsfEqdxHDMUc47WSLBNTOlrk=@AAJTSQACMDE=#

Use the read REST interface to verify the update.

Deleting an Identity Profile

The delete REST interface will remove the identity profile (defined as the value of the identity_name parameter) from the user data store. The following URL would delete the rest_user profile previously created.

http://OpenSSO-host:OpenSSO-port/opensso/identity/delete?identity_name=rest_user&admin=AQIC5wM2LY4Sfcwbg2YdVMaYsfEqdxHDMUc47WSLBNTOlrk=@AAJTSQACMDE=#&identity_type=user

Use the search REST interface to verify the deletion.

Now check out the not-most-recent-single-but-still-great-video from The Raveonettes: Black / White.

Sunday Aug 03, 2008

What Are You Doing The RESTful of Your Life?

I was looking for information on REST and found this great article on developers.sun.com. Check it out if you need to get REST.

And here is Miss Peggy Lee singing What Are You Doing The Rest If Your LIfe?
About

docteger

Search

Categories
Archives
« April 2014
SunMonTueWedThuFriSat
  
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
   
       
Today