Dashboard > JOSSO 1 > ... > Advanced Documentation > LDAP Integration
JOSSO 1
LDAP Integration
Added by Sebastian Gonzalez Oyuela, last edited by Alejandro Jadzinsky on Apr 25, 2008  (view change)
Labels: 
(None)

Prerequisites

Reference

For detailed information on all components and available configuration properties check out the Reference 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.

Modify the josso-gateway-config.xml configuration file located in the /WEB-INF/classes folder of the JOSSO web application.

Lets look at the josso-gateway.xml configuration file content :

<?xml version="1.0" encoding="ISO-8859-1" ?>
<domain>
  <name>SampleDomain</name>
  <type>web</type>
  <authenticator>
    <class>org.josso.auth.AuthenticatorImpl</class>

    <authentication-schemes>

        <!-- Basic Authentication Scheme -->
        <authentication-scheme>
          <name>basic-authentication</name>
          <class>org.josso.auth.scheme.UsernamePasswordAuthScheme</class>

          <!-- ================================================= -->
          <!-- LDAP Credential Store                             -->
          <!-- ================================================= -->
          <credential-store>
            <class>org.josso.gateway.identity.service.store.ldap.LDAPIdentityStore</class>
            <initialContextFactory>com.sun.jndi.ldap.LdapCtxFactory</initialContextFactory>
            <providerUrl>ldap://ldaphost</providerUrl>
            <securityPrincipal>cn=Manager,dc=my-domain,dc=com</securityPrincipal>
            <securityCredential>secret</securityCredential>
            <securityAuthentication>simple</securityAuthentication>
            <!-- Valid values are : SUBTREE, ONELEVEL -->
            <ldapSearchScope>SUBTREE</ldapSearchScope>
            <usersCtxDN>ou=People,dc=my-domain,dc=com</usersCtxDN>
            <principalUidAttributeID>uid</principalUidAttributeID>
            <rolesCtxDN>ou=Roles,dc=my-domain,dc=com</rolesCtxDN>
            <uidAttributeID>uniquemember</uidAttributeID>
            <roleAttributeID>cn</roleAttributeID>
            <credentialQueryString>
                uid=username,userPassword=password
            </credentialQueryString>
            <userPropertiesQueryString>
                mail=mail,cn=description
            </userPropertiesQueryString>

          </credential-store>
          <credential-store-key-adapter>
            <class>
              org.josso.gateway.identity.service.store.SimpleIdentityStoreKeyAdapter
            </class>
          </credential-store-key-adapter>
        </authentication-scheme>
      </authentication-schemes>
  </authenticator>

  <sso-identity-manager>
    <class>org.josso.gateway.identity.service.SSOIdentityManagerImpl</class>
    <!-- ================================================= -->
    <!-- LDAP Identity Store                               -->
    <!-- ================================================= -->
    <sso-identity-store>
      <class>org.josso.gateway.identity.service.store.ldap.LDAPIdentityStore</class>
      <initialContextFactory>com.sun.jndi.ldap.LdapCtxFactory</initialContextFactory>
      <providerUrl>ldap://ldaphost</providerUrl>
      <securityPrincipal>cn=Manager,dc=my-domain,dc=com</securityPrincipal>
      <securityCredential>secret</securityCredential>
      <securityAuthentication>simple</securityAuthentication>
      <!-- Valid values are : SUBTREE, ONELEVEL -->
      <ldapSearchScope>ONELEVEL</ldapSearchScope>
      <usersCtxDN>ou=People,dc=my-domain,dc=com</usersCtxDN>
      <principalUidAttributeID>uid</principalUidAttributeID>
      <rolesCtxDN>ou=Roles,dc=my-domain,dc=com</rolesCtxDN>
      <uidAttributeID>uniquemember</uidAttributeID>
      <roleAttributeID>cn</roleAttributeID>
      <credentialQueryString>
          uid=username,userPassword=password
      </credentialQueryString>
      <userPropertiesQueryString>
          mail=mail,cn=description
      </userPropertiesQueryString>
      <ldapSearchScope>SUBTREE</ldapSearchScope>
    </sso-identity-store>

    <sso-identity-store-key-adapter>
      <class>
      org.josso.gateway.identity.service.store.SimpleIdentityStoreKeyAdapter
      </class>
    </sso-identity-store-key-adapter>
  </sso-identity-manager>

  <sso-session-manager>
    <class>org.josso.gateway.session.service.SSOSessionManagerImpl</class>

    <!--
    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.
    -->
    <maxInactiveInterval>1</maxInactiveInterval>

    <sso-session-store>
      <class>
      org.josso.gateway.session.service.store.MemorySessionStore
      </class>
    </sso-session-store>

    <sso-session-id-generator>
      <class>
       org.josso.gateway.session.service.SessionIdGeneratorImpl
      </class>
      <!--
      The message digest algorithm to be used when generating session
      identifiers.  This must be an algorithm supported by the
      java.security.MessageDigest class on your platform.

      In J2SE 1.4.2 you can check :
      Java Cryptography Architecture API Specification & Reference -
      Apendix A : Standard Names
      Values are : MD2, MD5, SHA-1, SHA-256, SHA-384, SHA-512
      -->
      <algorithm>MD5</algorithm>
    </sso-session-id-generator>
  </sso-session-manager>

  <sso-audit-manager>
      <class>org.josso.gateway.audit.service.SSOAuditManagerImpl</class>
      <handlers>
          <handler>
              <class>org.josso.gateway.audit.service.handler.LoggerAuditTrailHandler</class>
              <name>LoggerAuditTrailHandler</name>
              <category>org.josso.gateway.audit.SSO_AUDIT</category>
          </handler>
      </handlers>
  </sso-audit-manager>

  <sso-event-manager>
      <class>org.josso.gateway.event.security.JMXSSOEventManagerImpl</class>
      <oname>josso:type=SSOEventManager</oname>
  </sso-event-manager>

</domain>

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.

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 some configuration properties have to be modified. Let's take a look at a sample based on the schema mentioned before :

<?xml version="1.0" encoding="UTF-8"?><domain>
    <name>JOSSO</name>
    <type>web</type>

    <authenticator>
        <class>org.josso.auth.AuthenticatorImpl</class>
        <authentication-schemes>
            <authentication-scheme>
                <name>basic-authentication</name>
 	        <class>org.josso.auth.scheme.BindUsernamePasswordAuthScheme</class>

                <!-- =============================================================== -->
                <!-- LDAP Credential Store                                           -->
                <!--                                                                 -->
                <!-- Chcek javadoc for configuration details :                       -->
                <!-- org.josso.gateway.identity.service.store.ldap.LDAPIdentityStore -->
                <!-- =============================================================== -->
                <credential-store>
		    <class>org.josso.gateway.identity.service.store.ldap.LDAPIdentityStore</class>
		    <initialContextFactory>com.sun.jndi.ldap.LdapCtxFactory</initialContextFactory>
		    <providerUrl>ldap://active-directory-host:389/</providerUrl>
		    <securityPrincipal>cn=Administrator,cn=USERS,dc=my-domain-controller</securityPrincipal>
		    <securityCredential>novascope</securityCredential>
		    <securityAuthentication>simple</securityAuthentication>
		    <ldapSearchScope>SUBTREE</ldapSearchScope>
		    <usersCtxDN>CN=Users,dc=my-domain-controller</usersCtxDN>
		    <principalUidAttributeID>sAMAccountName</principalUidAttributeID>
		    <rolesCtxDN>CN=Users,dc=my-domain-controller</rolesCtxDN>
		    <uidAttributeID>member</uidAttributeID>
		    <roleAttributeID>sAMAccountName</roleAttributeID>
		    <credentialQueryString>uid=sAMAccountName</credentialQueryString>
		    <userPropertiesQueryString>mail=mail,cn=description</userPropertiesQueryString>
                </credential-store>

                <!-- ================================================= -->
                <!-- Credential Store Key adapter                      -->
                <!-- ================================================= -->
                <credential-store-key-adapter>
                    <class>org.josso.gateway.identity.service.store.SimpleIdentityStoreKeyAdapter</class>
                </credential-store-key-adapter>

            </authentication-scheme>

        </authentication-schemes>
    </authenticator>

    <sso-identity-manager>

        <class>org.josso.gateway.identity.service.SSOIdentityManagerImpl</class>

        <!-- =============================================================== -->
        <!-- LDAP Identity Store                                             -->
        <!--                                                                 -->
        <!-- Chcek javadoc for configuration details :                       -->
        <!-- org.josso.gateway.identity.service.store.ldap.LDAPIdentityStore -->
        <!-- ================================================= -->
        <sso-identity-store>
	    <class>org.josso.gateway.identity.service.store.ldap.LDAPIdentityStore</class>
	    <initialContextFactory>com.sun.jndi.ldap.LdapCtxFactory</initialContextFactory>
	    <providerUrl>ldap://active-directory-host:389/</providerUrl>
	    <securityPrincipal>cn=Administrator,cn=USERS,dc=my-domain-controller</securityPrincipal>
	    <securityCredential>novascope</securityCredential>
	    <securityAuthentication>simple</securityAuthentication>
	    <ldapSearchScope>SUBTREE</ldapSearchScope>
	    <usersCtxDN>CN=Users,dc=my-domain-controller</usersCtxDN>
	    <principalUidAttributeID>sAMAccountName</principalUidAttributeID>
	    <rolesCtxDN>CN=Users,dc=my-domain-controller</rolesCtxDN>
	    <uidAttributeID>member</uidAttributeID>
	    <roleAttributeID>sAMAccountName</roleAttributeID>
	    <credentialQueryString>uid=sAMAccountName</credentialQueryString>
	    <userPropertiesQueryString>mail=mail,cn=description</userPropertiesQueryString>
        </sso-identity-store>

        <!-- ================================================= -->
        <!-- Identity Store Key adapter                        -->
        <!-- ================================================= -->
        <sso-identity-store-key-adapter>
            <class>org.josso.gateway.identity.service.store.SimpleIdentityStoreKeyAdapter</class>
        </sso-identity-store-key-adapter>
    </sso-identity-manager>

    <sso-session-manager>
        <class>org.josso.gateway.session.service.SSOSessionManagerImpl</class>
        <maxInactiveInterval>30</maxInactiveInterval>
        <maxSessionsPerUser>-1</maxSessionsPerUser>
        <invalidateExceedingSessions>false</invalidateExceedingSessions>
        <sessionMonitorInterval>10000</sessionMonitorInterval>
        <sso-session-store>
            <class>org.josso.gateway.session.service.store.MemorySessionStore</class>
        </sso-session-store>

        <sso-session-id-generator>
            <class>org.josso.gateway.session.service.SessionIdGeneratorImpl</class>
            <algorithm>MD5</algorithm>
        </sso-session-id-generator>
    </sso-session-manager>

    <sso-audit-manager>
        <class>org.josso.gateway.audit.service.SSOAuditManagerImpl</class>
        <handlers>
            <handler>
                <class>org.josso.gateway.audit.service.handler.LoggerAuditTrailHandler</class>
                <name>LoggerAuditTrailHandler</name>
                <category>org.josso.gateway.audit.SSO_AUDIT</category>
            </handler>
        </handlers>
    </sso-audit-manager>

    <sso-event-manager>
        <class>org.josso.gateway.event.security.JMXSSOEventManagerImpl</class>
        <oname>josso:type=SSOEventManager</oname>
    </sso-event-manager>

</domain>

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
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