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.