Title:     How to configure Single Sign-On (Extension)
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 default login mechanism relies on predefined users in the database with basic authentication or OpenId.
With a different [Spring security][1] configuration Apache Rave supports login based on request headers.

The following instructions assume there is already an SSO authentication service running in your network like [Shibboleth®][2]

##1) Get Apache Rave

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

##2) Build the Rave SSO extension

Run the following commands in your shell/terminal/command to build the Single Sign-On extension from the Sandbox:

    svn co http://svn.apache.org/repos/asf/rave/sandbox/rave-extensions/rave-extension-sso
    cd rave-extension-sso
    mvn install

##3) Add the Rave SSO Extension to the pom of your custom portal war

    <dependency>
      <groupId>org.apache.rave.extensions</groupId>
      <artifactId>rave-extension-sso</artifactId>
    </dependency>

##4) Add a custom Spring security configuration

Place the following Spring security configuration in your war overlay project (`/src/main/webapp/WEB-INF`) as `applicationContext-security-extension-sso.xml`

    <?xml version="1.0" encoding="UTF-8"?>
    <beans:beans xmlns:beans="http://www.springframework.org/schema/beans"
                 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                 xmlns="http://www.springframework.org/schema/security"
                 xsi:schemaLocation="http://www.springframework.org/schema/beans
           http://www.springframework.org/schema/beans/spring-beans-3.1.xsd
           http://www.springframework.org/schema/security
           http://www.springframework.org/schema/security/spring-security-3.1.xsd">

      <http use-expressions="true">
        <intercept-url pattern="/newaccount.jsp*" access="permitAll"/>
        <intercept-url pattern="/app/newaccount*" access="permitAll"/>
        <intercept-url pattern="/login.jsp*" access="permitAll"/>
        <intercept-url pattern="/css/**" access="permitAll"/>
        <intercept-url pattern="/images/**" access="permitAll"/>
        <intercept-url pattern="/script/**" access="permitAll"/>
        <intercept-url pattern="/app/admin/**" access="hasRole('ROLE_ADMIN')"/>
        <intercept-url pattern="/**" access="hasAnyRole('ROLE_USER','ROLE_ADMIN')"/>

        <form-login login-page="/login.jsp" authentication-failure-url="/login.jsp?authfail=sso"/>
        <logout logout-success-url="/../Shibboleth.sso/Logout?target=/portal"/>
        <!-- To remove SSO header authentication, comment out the following line -->
        <custom-filter ref="ssoHeaderFilter" position="PRE_AUTH_FILTER"/>
      </http>

      <!--
        REMOTE_USER is the header we're expecting.
        It's important that if we're using this header, the app is not accessed directly,
        instead accessed only through e.g. the Apache Shibboleth module, otherwise this header could be faked.
      -->
      <beans:bean id="ssoHeaderFilter"
                  class="org.apache.rave.portal.security.filter.SSORequestHeaderAuthenticationFilter">
        <beans:property name="principalRequestHeader" value="REMOTE_USER"/>
        <beans:property name="authenticationManager" ref="authenticationManager"/>
        <beans:property name="allowPreAuthenticatedPrincipals" value="true"/>
        <beans:property name="exceptionIfHeaderMissing" value="false"/>
        <beans:constructor-arg index="0" ref="userService"/>
        <beans:constructor-arg index="1" ref="ssoLoginHandler"/>
      </beans:bean>

      <beans:bean id="ssoLoginHandler" class="org.apache.rave.portal.security.impl.DefaultSSOLoginHandler">
        <beans:property name="autoCreateUser" value="true"/>
        <beans:property name="ssoHeaderEmail" value="Shib-InetOrgPerson-mail"/>
        <beans:property name="ssoHeaderDisplayName" value="displayName"/>
        <beans:property name="defaultPageLayout" value="columns_2"/>
        <beans:property name="defaultUserRole" value="ROLE_USER"/>
        <beans:constructor-arg index="0" ref="defaultNewAccountService"/>
        <beans:constructor-arg index="1" ref="userDetailsService"/>
        <beans:constructor-arg index="2" ref="defaultAuthorityService"/>
      </beans:bean>

      <beans:bean id="preauthAuthProvider"
                  class="org.springframework.security.web.authentication.preauth.PreAuthenticatedAuthenticationProvider">
        <beans:property name="preAuthenticatedUserDetailsService">
          <beans:bean id="userDetailsServiceWrapper"
                      class="org.springframework.security.core.userdetails.UserDetailsByNameServiceWrapper">
            <beans:property name="userDetailsService" ref="userDetailsService"/>
          </beans:bean>
        </beans:property>
      </beans:bean>

      <beans:bean id="userDetailsService" class="org.apache.rave.portal.service.impl.DefaultUserService"/>

      <authentication-manager alias="authenticationManager">
        <authentication-provider ref="preauthAuthProvider"/>
      </authentication-manager>

    </beans:beans>

Change the `web.xml`

    <context-param>
        <param-name>contextConfigLocation</param-name>
        <param-value>
            /WEB-INF/dataContext.xml
            /WEB-INF/applicationContext.xml
            /WEB-INF/applicationContext-security-extension-sso.xml
        </param-value>
    </context-param>

##5) Customize the login.jsp

Create your own login.jsp with e.g. a welcome text and a link to your SSO login form.


[1]: http://static.springsource.org/spring-security/site/docs/3.1.x/reference/springsecurity.html
[2]: http://shibboleth.net/