Chapter 10 Using the REST Identity Interfaces

OpenSSO Enterprise exposes a number of identity interfaces that support the Representational State Transfer (REST) architectural style. A RESTful web service assumes all components are exposed using the same, uniform application interface. From this high-level, we can use HTTP as a protocol that accomplishes this uniformity with its methods such as GET and POST. Thus calling the OpenSSO Enterprise RESTful interfaces requires the simple construction of a URL. The following sections contain information on invoking the available OpenSSO Enterprise REST interfaces.

• The REST URL Format

• Authentication

• Token Validation

• Logout

• Authorization

• Logging

• Searching Identity Types

• Display Identity Data

• Display Particular Identity Data

• Creating Identity Types

• Updating Identity Data

• Deleting an Identity Profile

The REST URL Format

The OpenSSO Enterprise REST 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

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. Refer to RFC 1738 for more information on unsafe characters and URL encoding. Some of the following sections contain examples of URL encoding.

Authentication

The authenticate REST interface opens an HTTP connection to authenticate a user with a POST operation. (Currently, the REST authenticate interface works with simple user name and password only.) The URL needs to be populated with the following information.

• username defines the user to be authenticated. The value is the Universal ID in the user's OpenSSO profile.

• password defines the password of the user to be authenticated.

• uri is optional and defines one or more URL parameters as documented in Accessing the OpenSSO Enterprise Authentication Service User Interface with a Login URL. See the sample URLs below.

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

In this URL, realm=sub-realm-name would need to be encoded in order for it to be treated as part of the value of uri as in:

http://OpenSSO-host:OpenSSO-port/opensso/identity/authenticate?username=jning&password=pwjning
&uri=realm%3Dsub-realm-name

You can define additional URL 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

In this URL, realm=sub-realm-name&service=ldapService would need to be encoded for both parameters to be treated as part of the value of uri as in:

http://OpenSSO-host:OpenSSO-port/opensso/identity/authenticate?username=jning&password=pwjning
&uri=realm%3Dsub-realm-name%26service%3DldapService

After successful authentication, a token string (tokenid) 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 Enterprise or for other fatal errors.

The tokenid returned is also applied as the value of the subjectid in some OpenSSO REST operations like logout and authorize. See the appropriate section in this chapter for more details.

Token Validation

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

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 subjectid (tokenid) that represents the user to be logged out of OpenSSO Enterprise.

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

The operation closes the session identified by the tokenid and logs the user out.

Authorization

The authorize REST interface will verify user authorization against created policies. Currently, the interface can check whether the user is authorized to perform a particular operation (GET or POST) on a particular HTTP resource. The URL needs to be populated with the following information.

• uri defines the resource for which authorization is being requested.

• action defines the operation for which authorization is being requested.

• subjectid defines the tokenid of the user for which authorization is being requested.

The following URL defines a user that wants to POST to http://www.sun.com:90.

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, the above URL would return true.

Logging

The log REST interface will log to the OpenSSO Enterprise 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. This is the value of the LOGGEDBY field in the log entry.

• subjectid defines the tokenid of the user about whom the log record is being written.

• logname is the module name of the OpenSSO Enterprise component invoking the Logging Service; for example, amAuthentication.

• message is the data being logged.

The following URL uses sample values to define these parameters.

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 a list of identities that match the input criteria. The URL needs to be populated with the following information.

• filter defines a set of criteria that controls what is returned by the operation. This is an optional parameter.

• attributes_names defines one or more LDAP attributes for which to search. This is an optional parameter.

• attribute_values_value-of-attributes_names defines the value of the attribute (as defined by attributes_names) that is being searched. This is an optional parameter.

• 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.

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

By default:

string=wsc
string=wsp
string=SecurityTokenService

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=#

By default:

string=amAdmin
string=amldapuser
string=dsameuser
string=anonymous
string=amService-URLAccessAgent
string=demo

The operation might also return TokenExpired, NeedMoreCredentials, or GeneralFailure on other errors.

Display Identity Data

The attributes REST interface will search the configured database for identity information about the defined user. 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. (It is assumed the user defined by subjectid has the appropriate permissions to display their own identity information.) The URL needs to be populated with the following information.

• subjectid defines the tokenid of the user whose identity information is being returned.

• attributes_names defines one or more LDAP attributes for which values will be returned. If not defined the URL would return all attributes in the profile.

This is an example URL that would return the specified attribute values from the 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

The operation might also return TokenExpired when the token has expired or GeneralFailure on other errors.

Display Particular Identity Data

The read REST interface will search the configured database for particular identity information about the user defined by name. The user defined by the admin attribute must have the permission to read the identity information. The URL needs to be populated with the following information.

• name defines the name of the identity whose profile will be read. The value is the Universal ID in the user's OpenSSO profile.

• attributes_names defines one or more LDAP attributes for which to search.

• identity_realm defines the realm in which the identity is configured. This is an optional parameter.

• admin defines the tokenid of the user with the necessary permissions to search; for example amadmin.

This is an example URL that would return the specified attribute values from the 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 

The operation might also return PermissionDenied if the user defined by admin does not have the appropriate permissions, TokenExpired when the token has expired or GeneralFailure on other errors.

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.

• identity_name defines the value of the Universal ID attribute in the user's OpenSSO profile.

• 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 identity_attribute_name) being created.

• identity_realm defines the realm in which the identity is to be created. This is an optional parameter.

• identity_type defines the type of identity being created.

• admin defines the tokenid of the user with the necessary permissions to search; for example amadmin.

This URL would create a user type.

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.

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.

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.

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=AQIC5wM2LY4SfcxCWBCNON1gTsaMaHISbYmTyYosv8pCPVw=@AAJTSQACMDE=#

Use the search REST interface to verify that the identity type has been created.

Updating Identity Data

The update REST interface will update an identity with the information defined in the URL. The URL needs to be populated with the following information.

• name defines the identity profile which is being updated. The value is the Universal ID in the user's OpenSSO profile.

• identity_attribute_names defines one or more LDAP attributes to be updated.

• identity_attribute_values_value-of-identity_attribute_names defines the value of the attribute (defined by identity_attribute_names) being updated.

• identity_realm defines the realm in which the identity is configured.

• admin defines the tokenid of the user with the necessary permissions to search; for example amadmin.

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=AQIC5wM2LY4SfcxCWBCNON1gTsaMaHISbYmTyYosv8pCPVw=@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 URL needs to be populated with the following information.

• identity_name defines the profile being deleted. The value is the Universal ID in the user's OpenSSO profile.

• identity_type defines the type of identity being deleted.

• identity_realm defines the realm in which the identity is configured.

• admin defines the tokenid of the user with the necessary permissions to delete a user profile; for example amadmin.

The following URL would delete the rest_user profile previously created.

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

Use the search REST interface to verify the deletion.