Sun OpenSSO Enterprise 8.0 Developer's Guide

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.

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

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:


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

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:


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.


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.