InomHitta mer dokumentationSupportresurser som ingår |  Ladda ner denna bok i PDF (2140 KB)
Chapter 10 Using the REST Identity InterfacesOpenSSO 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 FormatThe OpenSSO Enterprise REST operations are supported out of the box so no special configurations are required. The format of the URL is:
 Caution – 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. AuthenticationThe 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.
The following URL defines a username and password that will be authenticated at the OpenSSO root realm - by default, / (Top Level Realm).
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.
Tip – 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:
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).
Tip – 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:
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. Note – 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 ValidationThe 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.
The operation returns a value of true or false. LogoutThe 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.
The operation closes the session identified by the tokenid and logs the user out. AuthorizationThe 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.
The following URL defines a user that wants to POST to http://www.sun.com:90.
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. LoggingThe log REST interface will log to the OpenSSO Enterprise Logging Service. The URL needs to be populated with the following information.
The following URL uses sample values to define these parameters.
Searching Identity TypesThe 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.
The following URL would return the available agent types.
By default: string=wsc string=wsp string=SecurityTokenService This example would return all user entries.
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 DataThe 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.
This is an example URL that would return the specified attribute values from the user's LDAP profile.
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 DataThe 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.
This is an example URL that would return the specified attribute values from the user's LDAP profile.
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 TypesThe create REST interface will create the defined identity type in the configured data store. The URL needs to be populated with the following information.
This URL would create a user type.
The following URL would create a web agent profile for Policy Agent 3.0 types.
The following URL would create a J2EE agent profile for Policy Agent 3.0 types.
The following URL would create a 2.2 agent profile.
Tip – Use the search REST interface to verify that the identity type has been created. Updating Identity DataThe update REST interface will update an identity with the information defined in the URL. The URL needs to be populated with the following information.
The following URL would update the user profile with an email address.
Use the read REST interface to verify the update. Deleting an Identity ProfileThe 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.
The following URL would delete the rest_user profile previously created.
Use the search REST interface to verify the deletion. |
||||||||||||||||||||
|