DocTeger

OpenSSO Technical Information

And a Spoonful of Music

To Make the Medicine Go Down

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
• Token Validation
• Logout
• Authorization
• Logging
• Searching for Identity Types
• Display Identity Data
• Display Particular Identity Data
• Creating Identity Types
• Updating Identity Data
• Deleting an Identity Profile

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.

Posted at 02:47PM Oct 08, 2009 by Michael Teger in Sun  |  Comments[7]