Title:  LDAP Authentication
Notice:    Licensed to the Apache Software Foundation (ASF) under one
           or more contributor license agreements.  See the NOTICE file
           distributed with this work for additional information
           regarding copyright ownership.  The ASF licenses this file
           to you under the Apache License, Version 2.0 (the
           "License"); you may not use this file except in compliance
           with the License.  You may obtain a copy of the License at
           .
             http://www.apache.org/licenses/LICENSE-2.0
           .
           Unless required by applicable law or agreed to in writing,
           software distributed under the License is distributed on an
           "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
           KIND, either express or implied.  See the License for the
           specific language governing permissions and limitations
           under the License.

The authentication in the Apache Rave portal is handled through Spring Security.
The supported login mechanisms are currently basic authentication with users stored in the database, OpenId and, since
version 0.8-incubating, LDAP.

When an LDAP user logs in for the first time in the Apache Rave portal, a user profile in the portal is created with the
same username, email address and display name as in the LDAP. When this user logs in again, he is still authenticated
against the LDAP server.

## Demo login

For the LDAP authentication the demo setup comes with an embedded ApacheDS.
To login with the demo setup the following credentials can be used:

  * johnldap/johnldap
  * janeldap/janeldap

## LDAP configuration

The demo setup of the Apache Rave portal is configured to use an embedded ApacheDS, populated by a users.ldiff file:

    <security:ldap-server ldif="classpath:users.ldiff" root="dc=rave,dc=apache,dc=org" />

Authentication is handled by LDAP first. If this fails, Spring Security tries the basic authentication against the
database:

    <security:authentication-manager>
        <security:ldap-authentication-provider
                group-search-filter="member={0}"
                group-search-base="ou=groups"
                user-search-base="ou=people"
                user-search-filter="uid={0}"
                user-context-mapper-ref="raveUserContextMapper"/>

        <security:authentication-provider
                user-service-ref="userService">
            <security:password-encoder ref="passwordEncoder"/>
        </security:authentication-provider>
    </security:authentication-manager>

An Apache Rave portal specific class maps the authenticated LDAP user to an Apache Rave portal profile:

    <bean id="raveUserContextMapper" class="org.apache.rave.portal.web.security.LdapUserDetailsContextMapper" >
        <constructor-arg name="userService" ref="userService"/>
        <constructor-arg name="newAccountService" ref="defaultNewAccountService"/>
        <constructor-arg name="mailAttributeName" value="mail"/>
        <constructor-arg name="displayNameAttributeName" value="displayName"/>
        <constructor-arg name="pageLayoutCode" value="columns_3"/>
    </bean>

With "mailAttributeName" and "displayNameAttributeName" you can configure the names of the attributes from your own LDAP
that contain the mail address and display name for a user. When the LdapUserDetailsContextMapper create a user profile,
the user gets access to the portal and gets the layout configured in "pageLayoutCode".

## Customizing the LDAP setup

First create a custom portal project. There are multiple ways to build your custom Apache Rave instance, but the quickest is to
use a Maven WAR overlay. See [Extending Rave](rave-extensions.html) for an example overlay.

For the LDAP configuration, the default applicationContext-security.xml needs to be overridden.

### LDAP as only authentication provider

If you don't want the fallback to the database for authentication, remove:

    <security:authentication-provider user-service-ref="userService">
         <security:password-encoder ref="passwordEncoder"/>
    </security:authentication-provider>

### External LDAP server

The following line is configured to use the embedded ApacheDS:

    <security:ldap-server ldif="classpath:users.ldiff" root="dc=rave,dc=apache,dc=org" />

To use an external LDAP server, replace it with:

    <ldap-server id="appLdapServer"
            url="ldap://myldap.example.com:389/dc=example,dc=com"
            manager-dn="uid=admin,ou=system" manager-password="secret" />

<!-- AD documentation is commented out because configuration has not been confirmed yet -->
<!--
### Active directory

An Active Directory server behaves slightly different than other LDAP servers. In Spring Security there's a different
authentication provider that handles these differences. This requires a few extra changes in the
applicationContext-security.xml file.

Replace the default <security:authentication-manager> with:

    <security:authentication-manager>
        <security:authentication-provider ref="ldapAuthProvider"/>
    </security:authentication-manager>

Add a a bean for the configuration of ActiveDirectoryLdapAuthenticationProvider:

    <bean id="ldapAuthProvider"
          class="org.springframework.security.ldap.authentication.ad.ActiveDirectoryLdapAuthenticationProvider">
        <constructor-arg name="domain" value="mydomain.com"/>
        <constructor-arg name="url" value="ldap://adserver.mydomain.com"/>

        <property name="userDetailsContextMapper" ref="raveUserContextMapper"/>
    </bean>
-->

## Reference

  * [Spring Security LDAP documentation](http://static.springsource.org/spring-security/site/docs/3.1.x/reference/ldap.html)
  * [ApacheDS](http://directory.apache.org/apacheds/1.5/)
<!--  * [Active Directory](http://en.wikipedia.org/wiki/Active_Directory) -->