Dashboard > JOSSO 1 > ... > Developer > Reference
JOSSO 1
Reference
Added by Anonymous, last edited by Sebastian Gonzalez Oyuela on Jan 07, 2008  (view change)
Labels: 
(None)

JOSSO Components

JOSSO provides a component-oriented infrastructure that supports creating and combining multiple authentication schemes, credential, and session stores along with other type of components. For example, supporting certificate-based authentication is only a matter of implementing an authentication scheme component and referencing it from the JOSSO configuration.

This is the reference documentation for the main JOSSO components included in the distribution. Each component can be configured in JOSSO using either the buil-in IOC container or Spring, check out the Setup guides for details.

JOSSO Gateway

This are the main components used by the SSO Gateway, they are dynamically configured using JOSSO plugging capabilities.

Setup

For details on HOW-TO Configure this components in JOSSO, refer to the Setup guides.

  • WebConfiguration
    This represents some common configuration properties related to Web SSO.
  • Authenticator
    This is the component responsible of realizing a concrete authentication scheme
  • IdentityManager
    This is the component responsible of authenticating the user using the configured authenticator and managing the authenticated user sessions.
  • SessionManager
    This is the component responsible of managing the lifecycle of an SSO User Session.
  • AuditManager
    This is the component responsible for propagating auditing SSO events to the listening Audit Handlers.
  • EventManager
    This is the component responsible for propagating generic SSO events, such as information session lifecycle and authentication requests.
  • AuthenticationScheme
    Represents any authentication scheme used by an authenticator, like user&password, X.509 certificate, LDAP Bind, etc. An AuthenticationScheme defines the mechanism used to authenticate a user. Available implementations are :
  • CredentialStore
    This is a resource that provides credential storage functionallity. It's used to decouple authentication schemes from credential persistence mechanisms.
  • BindableCredentialStore
    This represents a credential store that can test a bind to the persistence mechanism using provided credentials. Used in combination with a BindUsernamePasswordAuthScheme allows JOSSO to delegate authentication process to the underlaying persistence mechanism, for example a DB or LDAP server like MS AD.
  • IdentityStore
    Represents a resource to store user information. Implementations define the specific persistence mechanism to store data.
    • DataSourceIdentityStore
      DataSource based implementation of a DB Identity and Credential store.
    • JDBCIdentityStore
      JDBC Implementation of a DB Identity and Credential Store.
    • LDAPBindIdentityStore
      An implementation of an Identity and Credential Store which obtains credential, user and role information from an LDAP server using JNDI, based on the configuration properties.
    • LDAPIdentityStore
      An implementation of an Identity and Credential Store which obtains credential, user and role information from an LDAP server using JNDI, based on the configuration properties.
    • MemoryIdentityStore
      Memory based implementation of an IdentityStore and CredentialStore that reads data from XML files.
  • SessionStore
    Represents a resource to store sessions. Implementations define the specific persistence mechanism to store sessions.
    • DataSourceSessionStore
      A DB session store that uses a DataSource to obtain connections to the DB server. The only configuration property specific to this implementation is the datasource JNDI name. It allows to reconstruct the session state after a system shutdown.
    • JdbcSessionStore
      This DB Session store obtains DB connections directly from the JDBC Driver. It allows to reconstruct the session state after a system shutdown.
    • MemorySessionStore
      This is a memory based store that uses a Map This implementation is thread safe.
    • SerializedSessionStore
      Session Store implementation which uses Java Serialization to persist Single Sign-On user sessions. It allows to reconstruct the session state after a system shutdown.
  • AuditTrailHandler
    This components process Audit Trails generated by the AuditManager. An Audit Handler can stop a SSO process like authentication if necessary, as part of a security policy.
  • EventListener
    This components receive SSO events propagated by the EventManager like user authentication, session expiraction, etc. The AuditManager is an implementation of an EventListener.

WebConfiguration

This represents common configuration properties releated with Web SSO, the configuration is located in the <sso-web-config> section of the josso-gateway-config.xml file.

Property Description
customLoginURL You can specify your own login URL, useful when you want to brand the login page
sessionTokenSecure If true, the SSO Token will require a secure connection

Authenticator

The authenticator validates if credentials are valid proof of user identity. It is the component responsible of realizing a concrete authentication scheme. An Authenticator can have multiple AuthenticationSchemes configured, executing them sequentially until a successfully authentication occurs.

Component Class : org.josso.auth.AuthenticatorImpl

IdentityManager

The Identity Manager is the component responsible of tracking of user and session associations and retrieving user information using the configured IdentityStore.

Component Class: org.josso.gateway.identity.service.SSOIdentityManagerImpl

SessionManager

The Session Manager handles SSO User Session life cycle, it creates new sessions when requested by the Gateway and monitors its activity. The Session Manager uses the configured SessionStore to keep session information.

Component Class: org.josso.gateway.session.service.SSOSessionManagerImpl

Property Description
maxInactiveInterval Set the maximum time interval, in minutes, between client requests before the SSO Service will invalidate the session. A negative time indicates that the session should never time out.
maxSessionsPerUser Max number of sessions per user, default 1. A negative value indicates that an unlimited number of sessions per user is allowed.
invalidateExceedingSessions If true, when the max number of sessions per user is exceeded, an already existing session will be invalidated to create a new one. If false, when the max number of sessions per user is exceeded, an exception is thrown and the new session is not created.
sessionMonitorInterval Time interval, in milliseconds, between exired sessions cleanup.

AuditManager

The Single Sign-On Audit Manager is the component responsible for propagating auditing SSO events to the listening Audit Handlers. Audit Handlers can trap such events and act accordingly, such as disabling an account after several failed authentication attempts (In this example its probably best to extend the default Authenticator to verify the user account status on authentication request).

JOSSO provides a default handler which traces all SSO audit trails using the configured logger.

Custom audit managers and their handlers can be configured and used, but for most cases the default configuration will do just fine.

This component will automatically register itself as a EventListener

Component Class: org.josso.gateway.audit.service.SSOAuditManagerImpl

EventManager

The Single Sign-On Event Manager is the component responsible for propagating generic SSO events, such as information session lifecycle and authentication requests. You can add your own [EventListener]s to act on behalf of any SSO event, such as an authentication failure. Even thought events are propagated through the JMX bus, your listeners do not have to deal with the JMX api since the underlying JOSSO event infrastructure will take care of this.

Custom event managers and their handlers can be configured and used, but for most cases the default configuration will do just fine.

Component Class : org.josso.gateway.event.security.JMXSSOEventManagerImpl

Property Description Sample Value
oname JMX Name of the EventManager MBean that will send SSO Events as JMX Notifications. The MBean will be registered by the MBeanComponentKeeper. josso:type=SSOEventManager

AuthenticationScheme

Represents any authentication scheme used by an authenticator, like user&password, X.509 certificate, LDAP Bind, etc.
The authentication mechanism should be :

  1. Initialize the AuthenticationScheme with input credentials received from user.
  2. Optionally get the principal name derived from input credentials.
  3. Authenticate the user providing known or trusted credentials.
  4. Confirm or cancel the authentication process.
  5. Optinalliy get private / public credentials. Authentication schemes are cloneable, a first instance is used as a "prototype" to build new ones.

UsernamePasswordAuthScheme

Basic authentication scheme, supporting username and password credentials.

Component Class : org.josso.auth.scheme.UsernamePasswordAuthScheme

Configuration properties supported by this authenticator are :

Property Description
hashAlgorithm The message digest algorithm to be used when hashing passwords. If not specified, no hashing is used. This must be an algorithm supported by the java.security.MessageDigest class on your platform.
hashEncoding The econding used to store hashed passwords. Supported values are HEX, BASE64.
ignorePasswordCase If true, password case will be igonred. This property is ignored if a hashAlgorithm was specified. Default to false.
ignoreUserCase If ture, username case will be ignored.
credential-store The credential store configured for this authenticator. Check specific stores for specific configuraiton options
credential-store-key-adapter The credential store key adapter configured for this authenticator. Check specific stores for specific configuraiton options

X509CertificateAuthScheme

X.509 Certificate-based Authentication Scheme. This authentication scheme receives X509 certificates as credential. The credential is received as part of a two-way SSL authentication.

Component Class : org.josso.auth.scheme.X509CertificateAuthScheme

BindUsernamePasswordAuthScheme

Basic authentication scheme, supporting username and password credentials.

This implementation relays on the configured CredentialStore to authenticate users. The configured store must be instance of BindableCredentialStore. If the bind operation provided by the store succeeds, the user is authenticated.

Component Class : org.josso.auth.scheme.BindUsernamePasswordAuthScheme

CredentialStore

This is a resource that provides credential storage functionallity. It's used to decouple authentication schemes from credential persistence mechanisms. Provided implementations are both Credential and Identity store instances.

BindableCredentialStore

This represents a credential store that can test a bind to the persistence mechanism using provided credentials. Used in combination with a BindUsernamePasswordAuthScheme allows JOSSO to delegate authentication process to the underlaying persistence mechanism, for example a DB or LDAP server like MS AD. This store provides a new operation : bind to test authentication.

IdentityStore

Represents a resource to store user information. Implementations define the specific persistence mechanism to store data. User data is accessed using the username as key. Provided implementations are both Credential and Identity store instances.

DataSourceIdentityStore

DataSource based implementation of a DB Identity and Credential store that retrieves user information using a DataSource. The DS must be defined in the container where the Gateway has been installed. Becase JOSSO can use your specific data structures, at least three SQL queries have to be configured to specify how information is retrieved from the DS. The alias is important in all queries as is used to map the retrieved value to a specific credential type.

Component Class : org.josso.gateway.identity.service.store.db.DataSourceIdentityStore

Property Description Sample Value
userQueryString Used to validate user existence , only used when the store is configured as Identity Store SELECT MY_USER FROM MY_USER_TABLE WHERE MY_USR = '?'
rolesQueryString Used to retrieve user's roles, only used when the store is configured as Identity Store SELECT MY_ROLE FROM MY_USER_ROLES_TABLE WHERE MY_USER = '?'
credentialQueryString Used to retrieve known credentials for a user.
This query depends on the configured authentication scheme. For a user / password based scheme the query could be
, only used when the store is configured as Credential Store 		SELECT MY_USER AS USERNAME, MY_PWD AS PASSWORD FROM MY_USER_TABLE WHERE MY_USER ='?'
dsJNDIName The JNDI name of the DataSource that will be used by the Store. java:/jdbc/MyDataSource

JDBCIdentityStore

JDBC Implementation of a DB Identity and Credential Store that retrieves user information establishing a DB connection using configuration information.

Component Class : org.josso.gateway.identity.service.store.db.JDBCIdentityStore

Property Description Sample Value
userQueryString Used to validate user existence , only used when the store is configured as Identity Store SELECT MY_USER FROM MY_USER_TABLE WHERE MY_USR = '?'
rolesQueryString Used to retrieve user's roles, only used when the store is configured as Identity Store SELECT MY_ROLE FROM MY_USER_ROLES_TABLE WHERE MY_USER = '?'
credentialQueryString Used to retrieve known credentials for a user.
This query depends on the configured authentication scheme. For a user / password based scheme the query could be
, only used when the store is configured as Credential Store 		SELECT MY_USER AS USERNAME, MY_PWD AS PASSWORD FROM MY_USER_TABLE WHERE MY_USER ='?'
connectionName The connection username to use when trying to connect to the database. myUsername
connectionPassword The connection password to use when trying to connect to the database. myPasswd
connectionURL The connection URL to use when trying to connect to the database. jdbc:oracle:thin:@localhost:1521:myDataBase
driverName The FQCN of the JDBC driver to use. oracle.jdbc.driver.OracleDriver

LDAPBindIdentityStore

An implementation of an Identity and Credential Store which obtains credential, user and role information from an LDAP server using JNDI, based on the configuration properties.

It allows to set whatever options your LDAP JNDI provider supports your Gateway configuration file. Examples of standard property names are:

  • initialContextFactory = "java.naming.factory.initial"
  • securityProtocol = "java.naming.security.protocol"
  • providerUrl = "java.naming.provider.url"
  • securityAuthentication = "java.naming.security.authentication"

This store implementation is both an Identity Store and Credential Store. Since in JOSSO the authentication of the user is left to the configured Authentication Scheme, this store implementation cannot delegate user identity assertion by binding to the LDAP server. For that reason it retrieves the required credentials from the directory leaving the authentication procedure to the configured Authentication Scheme. The store must be supplied with the configuratoin parameters so that it can retrieve user identity information.

Component Class : org.josso.gateway.identity.service.store.ldap.LDAPBindIdentityStore

Additional component properties include:

Property Description
securityPrincipal the DN of the user to be used to bind to the LDAP Server
securityCredential the securityPrincipal password to be used for binding to the LDAP Server.
securityAuthentication the security level to be used with the LDAP Server session. Its value is one of the following strings: "none", "simple", "strong". If not set, "simple" will be used.
ldapSearchScope alows control over LDAP search scope : valid values are ONELEVEL, SUBTREE
usersCtxDN the fixed distinguished name to the context to search for user accounts.
principalUidAttributeID the name of the attribute that contains the user login name. This is used to locate the user.
rolesCtxDN The fixed distinguished name to the context to search for user roles.
uidAttributeID the name of the attribute that, in the object containing the user roles, references role members. The attribute value should be the DN of the user associated with the role. This is used to locate the user roles.
roleAttributeID The name of the attribute that contains the role name
credentialQueryString The query string to obtain user credentials. It should have the following format : user_attribute_name=credential_attribute_name,... For example : uid=username,userPassword=password
userPropertiesQueryString The query string to obtain user properties. It should have the following format : ldap_attribute_name=user_attribute_name,... For example : mail=mail,cn=description

LDAPIdentityStore

An implementation of an Identity and Credential Store which obtains credential, user and role information from an LDAP server using JNDI, based on the configuration properties.

It allows to set whatever options your LDAP JNDI provider supports your Gateway configuration file. Examples of standard property names are:

  • initialContextFactory = "java.naming.factory.initial"
  • securityProtocol = "java.naming.security.protocol"
  • providerUrl = "java.naming.provider.url"
  • securityAuthentication = "java.naming.security.authentication"

This store implementation is both an Identity Store and Credential Store. Since in JOSSO the authentication of the user is left to the configured Authentication Scheme, this store implementation cannot delegate user identity assertion by binding to the LDAP server. For that reason it retrieves the required credentials from the directory leaving the authentication procedure to the configured Authentication Scheme. The store must be supplied with the configuratoin parameters so that it can retrieve user identity information.

Component Class : org.josso.gateway.identity.service.store.ldap.LDAPIdentityStore

Additional component properties include:

Property Description
securityPrincipal the DN of the user to be used to bind to the LDAP Server
securityCredential the securityPrincipal password to be used for binding to the LDAP Server.
securityAuthentication the security level to be used with the LDAP Server session. Its value is one of the following strings: "none", "simple", "strong". If not set, "simple" will be used.
ldapSearchScope alows control over LDAP search scope : valid values are ONELEVEL, SUBTREE
usersCtxDN the fixed distinguished name to the context to search for user accounts.
principalUidAttributeID the name of the attribute that contains the user login name. This is used to locate the user.
rolesCtxDN The fixed distinguished name to the context to search for user roles.
uidAttributeID the name of the attribute that, in the object containing the user roles, references role members. The attribute value should be the DN of the user associated with the role. This is used to locate the user roles.
roleAttributeID The name of the attribute that contains the role name
credentialQueryString The query string to obtain user credentials. It should have the following format : user_attribute_name=credential_attribute_name,... For example : uid=username,userPassword=password
userPropertiesQueryString The query string to obtain user properties. It should have the following format : ldap_attribute_name=user_attribute_name,... For example : mail=mail,cn=description

MemoryIdentityStore

Memory based implementation of an IdentityStore and CredentialStore that reads data from XML files. See josso-users.xml and josso-credentials.xml sample files.

Component Class : org.josso.gateway.identity.service.store.MemoryIdentityStore

Property Description
usersFileName The name of the XML file containing users information. Only used when configured as identity store.

credentialsFileName | The name of the XML file containing credentials information. Only used when configured as credential store. |

SessionStore

Represents a resource to store sessions. Implementations define the specific persistence mechanism to store sessions.

DataSourceSessionStore

A DB session store that uses a DataSource to obtain connections to the DB server.

Component Class : org.josso.gateway.session.service.store.db.DataSourceSessionStore

Component configuration properties include:

Property Description
sizeQuery The SQL Query used to add a new session to the store.
keysQuery The SQL Query used to retrieve all session ids. The first column for each row in the result set must be the session id.
loadAllQuery The SQL Query used to load all sessions from the store.
loadQuery The SQL Query used to load one session from the store based on its id.
loadByUserNameQuery The SQL Query used to load all sessions associated to a given user.
loadByLastAccesstimeQuery The SQL Query used to load all sessions last accessed before the given date.
loadByValidQuery The SQL Query used to load all sessions whose valid property is equals to the gvien argument.
deleteDml The SQL Query used to remove a session from the store.
deletAllDml The SQL Query used to remove ALL sessions from the store.
insertDml The SQL Query used to add a new session to the store.
dsJndiName The JNDI name of the DS associated to this Store.
Load Queries
  • The columns in the result set for all load methods must be in the following order :
    sessionId, userName, creationTime, lastAccessTime, accessCount, maxInactiveInterval, valid
  • lastAccessTime and creationTime are treated as a longs, not dates.

JdbcSessionStore

A DB session store that uses a JDBC to obtain connections to the DB server.

Component Class : org.josso.gateway.session.service.store.db.JdbcSessionStore

Component configuration properties include:

Property Description
sizeQuery The SQL Query used to add a new session to the store.
keysQuery The SQL Query used to retrieve all session ids. The first column for each row in the result set must be the session id.
loadAllQuery The SQL Query used to load all sessions from the store.
loadQuery The SQL Query used to load one session from the store based on its id.
loadByUserNameQuery The SQL Query used to load all sessions associated to a given user.
loadByLastAccesstimeQuery The SQL Query used to load all sessions last accessed before the given date.
loadByValidQuery The SQL Query used to load all sessions whose valid property is equals to the gvien argument.
deleteDml The SQL Query used to remove a session from the store.
deletAllDml The SQL Query used to remove ALL sessions from the store.
insertDml The SQL Query used to add a new session to the store.
connectionName The connection username to use when trying to connect to the database.
connectionPassword The connection password to use when trying to connect to the database.
connectionURL The connection URL to use when trying to connect to the database.
driverName The JDBC driver to use.
Load Queries
  • The columns in the result set for all load methods must be in the following order :
    sessionId, userName, creationTime, lastAccessTime, accessCount, maxInactiveInterval, valid
  • lastAccessTime and creationTime are treated as a longs, not dates.

MemorySessionStore

Default session store used by JOSSO, keeps session information in a Map, the implementation is thread safe.

Component Class : org.josso.gateway.session.service.store.MemorySessionStore

SerializedSessionStore

Session Store implementation which uses Java Serialization to persist Single Sign-On user sessions. It allows to reconstruct the session state after a system shutdown.

Component Class : org.josso.gateway.session.service.store.SerializedSessionStore

Property Description Sample Value
serializedFile File where serialized sessions will be stored (optional) /var/josso/josso_sessions.ser

AuditTrailHandler

This are components that receive audit trails as events propagated by the AuditManager. AuditTrailHandlers implement the handle method, after processing the event, an AuditTrailHandler can decide to continue the process or to stop it.

The Auditing infrastructure in JOSSO is based on the SSOEventManager component.

A default implementation is provided that only logs audit trails

Component Interface : org.josso.gateway.audit.service.handler.SSOAuditTrailHandler

LoggerAuditTrailHandler

Audit Trail handler that will log all audit trails.

Component Class : org.josso.gateway.audit.service.handler.LoggerAuditTrailHandler

Property Description
category The logging category used to send audit trail information. This allows you to configure the logging infrastructure specifically for this category.

EventListener

This components handle *SSOEvent*s generated by the EventManager like user authentication, session expiration, etc. The AuditManager is for example an Event Listener

Component Interface : org.josso.gateway.event.SSOEventListener

Comments

Care to comment on this How-To? Help keep this document relevant by passing along any constructive feedback to the josso-docs
Site running on a free Atlassian Confluence Open Source Project License granted to JOSSO. Evaluate Confluence today.
Powered by Atlassian Confluence, the Enterprise Wiki. (Version: 2.6.0 Build:#913 Sep 27, 2007) - Bug/feature request - Contact Administrators