com.iona.security.is2adapter
Interface IS2Adapter

public interface IS2Adapter

This interface defines the methods which must be implemented by an adapter for a specific enterprise security system which stores users and potentially roles.

The IONA security service dynamically loads adapters implementing this interface through a properties file. Normally, this property file is called is2.properties.
In this properties file, the first property to specify is the adapter's name, such as "file", "LDAP", etc.

     com.iona.isp.adapters=<adapter_name>
 e.g. If you want to call your adapter as "MyAdapter", then
     com.iona.isp.adapters=MyAdapter
 

The next property to specify is the adapter's class name.

     com.iona.isp.adapter.<adapter_name>.class
 e.g. If the adapter's name is com.foo.security.MyAdapter, then
     com.iona.isp.adapter.MyAdapter.class=com.foo.security.MyAdapter
 

All configurable properties for this adapter should be specified using a property name like this:

     com.iona.isp.adapter.<adapter_name>.param.<property_name>
 

For example, if the adapter needs two parameters to be configured, a host address called "host" and port number called "port". This could be achieved by defining two properties as following

     com.iona.isp.adapter.MyAdapter.param.host=www.foo.com
     com.iona.isp.adapter.MyAdapter.param.port=10389
 

During iS2's startup, the adapter class specified would be loaded dynamically. All properties defined for this adapter like above would be loaded and the prefix of the properties name "com.iona.isp.adapter.<adapter_name>.param" would be stripped off. The properties passed into your adapter's initialize() method would look like the following given the above example:

     host=www.foo.com
     port=10389
 

See Also:

AuthenticatedPrincipal

Field Summary

static int

version

Method Summary

AuthenticatedPrincipal	authenticate(java.lang.String userName, java.lang.String password) Authenticate a user using name and password.
AuthenticatedPrincipal	authenticate(java.lang.String realmName, java.lang.String userName, java.lang.String password) Authenticate a user using name and password.
AuthenticatedPrincipal	authenticate(java.lang.String realmName, java.security.cert.X509Certificate certificate) Authenticate a principal using a X509 certificate.
AuthenticatedPrincipal	authenticate(java.security.cert.X509Certificate certificate) Authenticate a principal using a X509 certificate.
void	close() Close the adapter.
java.util.ArrayList	getAllUsers() This method currently is not used by iS2 during runtime.
AuthenticatedPrincipal	getAuthorizationInfo(AuthenticatedPrincipal principal) Get authorization information from adapter, such as user's roles, etc.
AuthenticatedPrincipal	getAuthorizationInfo(java.lang.String userName) Deprecated. use getAuthorizationInfo(AuthenticatedPrincipal principal) instead
AuthenticatedPrincipal	getAuthorizationInfo(java.lang.String realmName, java.lang.String userName) Deprecated. use getAuthorizationInfo(AuthenticatedPrincipal principal) instead
void	initialize(java.util.Properties props) Initialize the adapter based on the configurable properties.
void	logout(AuthenticatedPrincipal ap) Logout the principal from enterprise security system.

Field Detail

version

public static final int version

Method Detail

initialize

public void initialize(java.util.Properties props)
                throws IS2AdapterException

Initialize the adapter based on the configurable properties.

This method will only be called once after the adapter has been loaded. Do all necessary one-time initialization here. All configurable properties for this adapter will be passed in from the IONA security service.

Parameters:

props - Properties used to initialize the adapter

Throws:

IS2AdapterException - if any error happens

authenticate

public AuthenticatedPrincipal authenticate(java.lang.String userName,
                                           java.lang.String password)
                                    throws IS2AdapterException

Authenticate a user using name and password.

Roles might be retrieved from enterprise security system and returned after successful authenticaion if iS2 authorization manager is not used. If roels would be returned, this method should return roles defined for this user in all realms.

If iS2's single sign on (SSO) is enabled and user's authorization info, such as user's role, needs to be retrieved, it should be done in this method. Use the AuthenticatedPrincipal.addRole(String) method to populate the user's roles.

Parameters:

userName - user's name. If a security domain is specified, user name could be in format SecurityDomain\UserID

password - user's password

Returns:

AuthenticatedPrincipal object if authentication is successful.

Throws:

IS2AdapterException - if authentication is not successful

See Also:

AuthenticatedPrincipal

authenticate

public AuthenticatedPrincipal authenticate(java.lang.String realmName,
                                           java.lang.String userName,
                                           java.lang.String password)
                                    throws IS2AdapterException

Authenticate a user using name and password.

Roles might be retrieved from enterprise security system and returned after successful authenticaion if iS2 authorization manager is not used.

If single sign on is done by iS2, realmName would be ignored. Roles from all realms should be returned. Curently realmName is researved for future support of single sign on in adapter.

If iS2's single sign on (SSO) is enabled and user's authorization info, such as user's role, needs to be retrieved, it should be done in this method. Use the AuthenticatedPrincipal.addRole(String) method to populate the user's roles.

Parameters:

realmName - user's realm name

userName - user's name. If a security domain is specified, user name could be in format SecurityDomain\UserID

password - user's password

Returns:

AuthenticatedPrincipal object if authentication is successful.

Throws:

IS2AdapterException - if authentication is not successful

See Also:

AuthenticatedPrincipal

authenticate

public AuthenticatedPrincipal authenticate(java.security.cert.X509Certificate certificate)
                                    throws IS2AdapterException

Authenticate a principal using a X509 certificate.

Roles might be retrieved from enterprise security system and returned if choose so after successful authenticaion.

Roles might be retrieved from enterprise security system and returned after successful authenticaion if iS2 authorization manager is not used.

If single sign on is done by iS2, realmName would be ignored. Roles from all realms should be returned. Curently realmName is researved for future support of single sign on in adapter.

If user's authorization info needs to be retrieved, it should be done in this method (currently only the user's list of roles is supported). Use the AuthenticatedPrincipal.addRole(String) method to populate the user's roles.

If certificate based authentication is not required, this method will not be used.

Parameters:

certificate - user's X509 certificate

Returns:

AuthenticatedPrincipal object if authentication is successful.

Throws:

IS2AdapterException - if authentication is not successful

See Also:

AuthenticatedPrincipal

authenticate

public AuthenticatedPrincipal authenticate(java.lang.String realmName,
                                           java.security.cert.X509Certificate certificate)
                                    throws IS2AdapterException

Authenticate a principal using a X509 certificate.

Roles might be retrieved from enterprise security system and returned after successful authenticaion if iS2 authorization manager is not used.

If single sign on is done by iS2, realmName would be ignored. Roles from all realms should be returned. Curently realmName is researved for future support of single sign on in adapter.

If user's authorization info needs to be retrieved, it should be done in this method (currently only the user's list of roles is supported). Use the AuthenticatedPrincipal.addRole(String) method to populate the user's roles.

If certificate based authentication is not required, this method will not be used.

Parameters:

realmName - realm name

certificate - user's X509 certificate

Returns:

AuthenticatedPrincipal object if authentication is successful.

Throws:

IS2AdapterException - if authentication is not successful

See Also:

AuthenticatedPrincipal

logout

public void logout(AuthenticatedPrincipal ap)
            throws IS2AdapterException

Logout the principal from enterprise security system. Do any cleanup for this user.

Parameters:

ap - AuthenticatedPrincipal object

Throws:

IS2AdapterException - if logout failed

See Also:

AuthenticatedPrincipal

getAuthorizationInfo

public AuthenticatedPrincipal getAuthorizationInfo(AuthenticatedPrincipal principal)
                                            throws IS2AdapterException

Get authorization information from adapter, such as user's roles, etc.

This method will be called in case of Cross domain Single Sign On (SSO).

In case of Cross Domain Single Sign On(CDSSO), one iSF instance might reside in one domain, and the other iSF instance resides in another domain. They have different Enterprise Security System underneath them and users have different roles (even Ids) and access control rules in those domains. In this case, is2.domain.name property should be set in is2.properties.

For example, let's say we have two domains, in one, users info is stored in LDAP, and the other, stored in Oracle database. In correspondence, two iSF instances are used, one connects to LDAP(iSF1), and the other to Oracle(iSF2). In iSF1, is2.domain.name is set to "LDAP" and in iSF2, as "Oracle".

First let's consider a simple case, users in those two systems share common User ID.

In this case, first user authenticates itself to LDAP (iSF1), a token and an AuthenticatedPrincipal object with authorization info in LDAP domain are sent back to him after successful authentication, so that he can access resources in this LDAP domain based on his access control rules there. Then he tries to access resources in Oracle domain, in order to do that, he first sends the token he received from iSF1 to iSF instance in Oracle domain (iSF2) for authentication. After iSF2 receives the token, it finds out that it is a token issued by iSF1 based on its cluster configuration file. Therefore, it sends the token to iSF1 for token authentication. In iSF1, after the token is authenticated successfully, the user�s authorization info, together with issuer domain name(LDAP) are sent back to iSF2. In iSF2, after the authenticated principal is received from iSF1 from token authentication, it sees that the issuer domain of the user info he got back is different from its own domain name.

At this time, it would call this method to retrieve the authorization info for this user in its own domain. Then this AuthenticatedPrincipal object with authorization info of this domain(Oracle instead of LDAP) filled in would be returned to the client.

Of course, in a custom adapter, it can so implemented that authorization info from both domains would be returned to client, if the custom requirements are so desired.

In case in those domains, user has different User ID, AuthenticatedPrincipal object (since 6.1) can contain multiple principals. The method AuthenticatedPrincipal.addPrincipal(Principal p) could be used to populate multiple principals for this user.

This method could also be used to replace the deprecated getAuthorizationInfo(String userID) and getAuthorizationInfo(String realm, String userID)
But those use scenarios are deprecated also.

Parameters:

principal - an AuthenticatedPrincipal object obtained from other domain

Returns:

AuthenticatedPrincipal object which has the user's authorization info filled in

Throws:

IS2AdapterException - if any error happens

See Also:

AuthenticatedPrincipal

getAuthorizationInfo

public AuthenticatedPrincipal getAuthorizationInfo(java.lang.String userName)
                                            throws IS2AdapterException

Deprecated. use getAuthorizationInfo(AuthenticatedPrincipal principal) instead

Get authorization information from adapter, such as user's roles, etc.

This method will only be called if iS2's Single Sign On (SSO) feature has been disabled.
If SSO is disabled, authentication method of iSF will call this method to retrieve the user's authorization info. Use the AuthenticatedPrincipal.addRole(String) method to populate the user's roles.
If SSO is not disabled, the user's authorization infomation will be retrieved back by authenticate(String userName, String password) or authenticate(X509Certificate certificate), and saved by that method into the AuthenticatedPrincipal object using the addRole() method.

Parameters:

userName - user's name

Returns:

AuthenticatedPrincipal object which has the user's authorization info filled in

Throws:

IS2AdapterException - if any error happens

See Also:

AuthenticatedPrincipal

getAuthorizationInfo

public AuthenticatedPrincipal getAuthorizationInfo(java.lang.String realmName,
                                                   java.lang.String userName)
                                            throws IS2AdapterException

Deprecated. use getAuthorizationInfo(AuthenticatedPrincipal principal) instead

Get authorization information from adapter, such as user's roles, etc for a specific realm and global realm.

This method will only be called if iS2's Single Sign On (SSO) feature has been disabled.
If SSO is disabled, com.iona.security.common.AuthManager#authenticateToken(String token, String userName) will call this method to retrieve the user's authorization info. Use the AuthenticatedPrincipal.addRole(String) method to populate the user's roles.
If SSO is not disabled, the user's authorization infomation will be retrieved back by authenticate(String userName, String password) or authenticate(X509Certificate certificate), and saved by that method into the AuthenticatedPrincipal object using the addRole() method.

Parameters:

realmName - realm name

userName - user's name

Returns:

AuthenticatedPrincipal object which has the user's authorization info filled in

Throws:

IS2AdapterException - if any error happens

See Also:

AuthenticatedPrincipal

close

public void close()
           throws IS2AdapterException

Close the adapter. Do necessary clean up and free up resources.

Throws:

IS2AdapterException - if anything goes wrong during shutdown

getAllUsers

public java.util.ArrayList getAllUsers()
                                throws IS2AdapterException

This method currently is not used by iS2 during runtime. It is reserved for future use. The easiest way is to put an empty implementation like this for now:

   public ArrayList getAllUsers() throws IS2AdapterException {
        return null;
   }
 

Returns:

array of AuthenticatedPrinicipals

Throws:

IS2AdapterException - if any error happens