For detailed information on all components and available configuration properties check out the SSO Plugins guide.
You should first setup JOSSO for one of the supported platforms such as Tomcat and JBoss.
Check the specific Setup HOW-TO corresponding to the platform where JOSSO is going to be installed.
Once you're done with the initial setup make sure that the JOSSO web application is accessible.
In order to use a Directory as the store for user and role information, an LDAP server accessible from the JOSSO Gateway. The TCP/IP ports involved in an LDAP session are the 389 and the 636 for SSL.
JOSSO has been tested with OpenLDAP and ActiveDirectory but it should work with virtually any standard LDAP server.
OpenLDAP can be downloaded from here.
This How-To will explain how to integrate JOSSO Single Sign-On with an LDAP server as a store for user and role information.
It will implement an LDAP Store, configured for providing authentication information, like the user password, using the LDAP protocol.
If you have your own schema already setup, this step is not required. You should instead
update the josso-gateway-config.xml file so that user and role information can be obtained.
You should create a namespace which should contain user and role entries. Lets have a look at an example
The LDIF file should be imported into the LDAP server using the specific command available for this task in the LDAP server product. In case of using OpenLDAP you should use the ldapadd command.
On succesfull creation of the schema, the Directory should look like the following :
Now we need to tell the Single Sign-On Gateway how to obtain user and role information from the LDAP server in order to authenticate users.
We'll also tell the Single Sign-On Gateway how to load the properties of the user.
Include the Ldap identity store declaration onto the josso-gateway-ldap-stores.xml descriptor :
The LDAP credential and identity store properties are :
- 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 : the search scope used for querying the LDAP server. Valid values are SUBTREE and ONELEVEL. This property applies only for searching for users, not roles.
- 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
Make sure you set your specific values for the providerUrl, securityPrincipal, securityCredential elements according to your LDAP settings.
Do this for both the Credential Store and Identity Manager settings.
Finally, include the descriptor declaring the Ldap identity store from the gateway's main descriptor
This section describes how to configure JOSSO to work with MS Active Directory.
The main issue with Active Directory is that it does not allow retrieving the user password value, therefore JOSSO cannot verify the supplied credentials during the authentication process. To overcome this limitation, JOSSO comes with two components which can authenticate users by performing a bind against the configured persistence mechanism using the credentials provided by the authenticating user. If the bind succeeds, the user is considered authenticated.
The first component is an extension of the basic authentication scheme provided with JOSSO. This extension, known as BindUsernamePasswordAuthScheme, relays on the configured Credential Store to authenticate users, being such store of type BindableCredentialStore. If the bind operation provided by the store succeeds, the user is considered authenticated.
The second component is a CredentialStore implementation known as the BindableCredentialStore. This type of store provides a new operation that, based on the supplied user name and password, binds to the underlaying persistence mechanism, returning true if the bind succeeds.
Even thought this additional components are aimed to support Active Directory, they could be used against directories of other vendors. JOSSO currently provides an LDAP BindIdentityStore implementation but future releases could include new bindable stores that would support user authentication by binding to other persistence mechanisms such as a RDBMS.
To work with Active Directory identity store properties need to be changed . Let's take a look at a binding ldap identity store declaration on the schema mentioned before :
We also have to use the bind-auth-scheme instead of the default. This auth scheme will authenticate users if the bind operation provided by the store succeedds. Remember to remove or comment JOSSO basic authentication scheme from this file.
Read the Developer HOW-TO.
Care to comment on this How-To? Help keep this document relevant by passing along any constructive feedback to the josso-docs