Added by Sebastian Gonzalez Oyuela, last edited by Sebastian Gonzalez Oyuela on Mar 19, 2009  (view change)

Labels:

Enter labels to add to this page:
Wait Image 
Looking for a label? Just start typing.

Prerequisites

Reference

For detailed information on all components and available configuration properties check out the SSO Plugins guide.

Install and Configure JOSSO

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.

Availability of an LDAP server

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.

Introduction

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.

Create the schema

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

LDIF file: # OU DEFINITIONS
# People OU - for holding records of all individuals
dn: ou=People,dc=my-domain,dc=com
ou: People
objectClass: top
objectClass: organizationalUnit

# Roles OU - for holding records of roles and the users to which those roles
# have been assigned
dn: ou=Roles,dc=my-domain,dc=com
ou: Roles
objectClass: top
objectClass: organizationalUnit

# PEOPLE ENTRIES
dn: uid=user1,ou=People,dc=my-domain,dc=com
objectClass: top
objectClass: person
objectClass: organizationalPerson
objectClass: inetOrgPerson
sn: User1 SN
cn: User1 CN
uid: user1
userpassword: user1pwd
mail: user1@josso.org

dn: uid=user2,ou=People,dc=my-domain,dc=com
objectClass: top
objectClass: person
objectClass: organizationalPerson
objectClass: inetOrgPerson
sn: User2 SN
cn: User2 CN
uid: user2
userpassword: user2pwd
mail: user2@josso.org

# ROLES ENTRIES
dn: cn=role1,ou=Roles,dc=my-domain,dc=com
objectClass: top
objectClass: groupOfUniqueNames
cn: role1
uniqueMember: uid=user1,ou=People,dc=my-domain,dc=com

dn: cn=role2,ou=Roles,dc=my-domain,dc=com
objectClass: top
objectClass: groupOfUniqueNames
cn: role2
uniqueMember: uid=user2,ou=People,dc=my-domain,dc=com

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 :

Configure the SSO Gateway

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 :

<?xml version="1.0" encoding="ISO-8859-1" ?>
<s:beans xmlns:s="http://www.springframework.org/schema/beans"
         xmlns:ldap-istore="urn:org:josso:ldap:identitystore"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="
        http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.5.xsd
         urn:org:josso:ldap:identitystore http://www.josso.org/schema/josso-ldap-identitystore.xsd"
        >

    <ldap-istore:ldap-store
            id="josso-identity-store"
            initialContextFactory="com.sun.jndi.ldap.LdapCtxFactory"
            providerUrl="ldap://localhost:10389"
            securityPrincipal="uid=admin,ou=system"
            securityCredential="secret"
            securityAuthentication="simple"
            ldapSearchScope="SUBTREE"
            usersCtxDN="ou=People,dc=my-domain,dc=com"
            principalUidAttributeID="uid"
            uidAttributeID="uniquemember"
            rolesCtxDN="ou=Roles,dc=my-domain,dc=com"
            roleAttributeID="cn"
            credentialQueryString="uid=username,userPassword=password"
            updateableCredentialAttribute="userPassword"
            userPropertiesQueryString="mail=mail,cn=description"
            />
</s:beans>

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
josso-gateway-config.xml

<?xml version="1.0" encoding="ISO-8859-1" ?>
<s:beans xmlns:s="http://www.springframework.org/schema/beans"
       xmlns="urn:org:josso:core"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="
        http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.5.xsd
        urn:org:josso:core http://www.josso.org/schema/josso-core.xsd">

    ...

    <s:import resource="josso-gateway-ldap-stores.xml" />

    ...
</s:beans>

Using MS Active Directory

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 :

<?xml version="1.0" encoding="ISO-8859-1" ?>
<s:beans xmlns:s="http://www.springframework.org/schema/beans"
         xmlns:ldap-istore="urn:org:josso:ldap:identitystore"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="
        http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.5.xsd
         urn:org:josso:ldap:identitystore http://www.josso.org/schema/josso-ldap-identitystore.xsd"
        >

        <ldap-istore:ldap-bind-store
            id="josso-identity-store"
	    initialContextFactory="com.sun.jndi.ldap.LdapCtxFactory"
	    providerUrl="ldap://127.0.0.1:389"
	    securityPrincipal="cn=Administrator,cn=USERS,dc=my-domain"
	    securityCredential="secret"
	    securityAuthentication="simple"
	    ldapSearchScope="SUBTREE"
	    usersCtxDN="CN=Users,dc=my-Domain"
	    principalUidAttributeID="sAMAccountName"
	    uidAttributeID="member"
	    rolesCtxDN="CN=Users,dc=my-domain"
	    roleAttributeID="sAMAccountName"
	    updateableCredentialAttribute="userPassword"
	    userPropertiesQueryString="mail=mail,cn=description"
            />

</s:beans>

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.

josso-gateway-auth.xml
    <!-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -->
    <!-- BIND Authentication Scheme (normally LDAP) -->
    <!-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -->
    <bind-authscheme:bind-auth-scheme
            id="josso-bind-authentication"
            name="basic-authentication"
            hashAlgorithm="MD5"
            hashEncoding="HEX"
            ignorePasswordCase="false"
            ignoreUserCase="false">


        <bind-authscheme:credentialStore>
            <s:ref bean="josso-identity-store"/>
        </bind-authscheme:credentialStore>

        <bind-authscheme:credentialStoreKeyAdapter>
            <s:ref bean="josso-simple-key-adapter"/>
        </bind-authscheme:credentialStoreKeyAdapter>

    </bind-authscheme:bind-auth-scheme>

For more information

Read the Developer HOW-TO.

Comments

Care to comment on this How-To? Help keep this document relevant by passing along any constructive feedback to the josso-docs