Authentication

The PureWeb server uses Spring Security role-based authorization to control login authentication and authorization. Detailed information on this model can be found at the following location:
http://static.springsource.org/spring-security/site/docs/3.1.x/reference/springsecurity.html

Any authorization plug-in that conforms to the Spring 3.1.x security model will work, as long as it grants applicable security roles supported by the PureWeb SDK.

Spring Security includes a built-in LDAP provider, but this provider does not have the ability to map LDAP groups to custom roles. To offer this functionality, the PureWeb server uses its own LDAP provider, MappedLdapAuthenticationProvider, which is otherwise similar to the one included with Spring Security. You add this provider through a plugin.xml file.

Once you have set up your authentication, you can restrict access to pages based on a user's role.

The configuration files also allow you to control how the application responds to an unauthorized access attempt.

For instructions on how to add users, and how to assign passwords and security roles, see User Management.

Security Roles

The roles required by the PureWeb SDK are as follows:

  • Administrator: This role is used to perform administrative tasks in the server. It has access to all the server’s menu options. It is the only role who has access to the server's Configuration page and who is authorized to cancel sessions that are in progress. In Spring, it is defined as ROLE_PUREWEB_SERVER_ADMIN.
  • User: This role is used for normal users of PureWeb applications, for instance it can launch client applications. When logged in with User level permissions, you do not have access to any of the server pages, except the Apps page. In Spring, it is defined as ROLE_PUREWEB_USER.
  • Monitor: This role is used for monitoring the server; it does not have access to the configuration pages, and cannot launch applications. In Spring, it is defined as ROLE_PUREWEB_SERVER_MONITOR.
  • Collaborator: This role is used internally by the SDK to define permissions for collaborators who join a session. In Spring, it is defined as ROLE_PUREWEB_COLLABORATOR.
  The default configuration includes an additional role ROLE_PUREWEB_USER_ADMIN that is not currently used, but left in the default admin user credentials for legacy reasons.

Configuring an LDAP Plug-in

The PureWeb server uses Spring Security role-based authorization. Spring Security includes a built-in LDAP provider, but this provider does not have the ability to map LDAP groups to custom roles. To offer this functionality, the server uses its own LDAP provider, MappedLdapAuthenticationProvider, which is otherwise similar to the one included with Spring Security.

The simplest way to use this provider is through a plug-in.

  1. Create a new text file called ldap-plugin.xml and place it at the following location:
    [installed_directory]\Server\conf
  2. Add the provider bean below to this file.
  3. Edit the parameters in the bean to reflect the values for your own implementation. The parameters need to match the LDAP parameters used by your directory.

Controlling Access to Applications

Using the PureWeb server, you can restrict access to pages by editing the security policies found in the pureweb-context.xml file. These policies are based on security roles.

You can navigate to this configuration file in two ways:

  • Go to the server's Configuration page. Scroll down the page until you see that file's name as a link. Click the link to open the file for editing in the browser.
  • Open the file directly in a text editor. Its location in the server directory is as follows:
    [installed_directory]\Server\webapp\WEB-INF\pureweb-context.xml

Once the file is open:

  1. Edit the values of the intercept-url pattern and access elements. For example:

    <s:intercept-url pattern="/pureweb/app/**" access="hasRole('ROLE_PUREWEB_USER')"/>

  1. Click Save to commit the changes.
  2. Close the file.

You must perform a reload or restart the server before server configuration or plug-in file changes take effect.

To perform a reload, navigate to the server's Configuration page and click the Reload button for the section where the file is located within the page (for example, if you edited a plug-in configuration file, click the Reload Plugins button, if you edited a logging configuration file, click the Reload Logging button, and so on).

If you edit a configuration file, the server will display a reload required message beside this file in the Configuration page as a reminder until the changes have been applied.

Restricting Collaboration Access to Authenticated Users

By default, any user who has the share URL and password can join a PureWeb collaboration session. However, you may change this behavior so that only users who are already authenticated may join.

Restricting collaboration access to authenticated users is only supported when collaboration participants directly access the share URL. It is not supported when using the client-side joinSession method to bring a participant into a session.

  1. Navigate to the PureWeb server's Configuration page. Under System Configuration, click the pureweb-context.xml link to open the file.
  2. Navigate to the following code snippet:

    <!-- pureweb collaboration -->
    <!-- Allow anonymous access to collaboration -->
    <s:intercept-url pattern="/pureweb/share" access="hasAnyRole('ROLE_PUREWEB_USER', 'ROLE_PUREWEB_COLLABORATOR')"/>    
    
    <!-- Force ROLE_PUREWEB_USER access to collaboration (comment out line above)
    <s:intercept-url pattern="/pureweb/share" access="hasRole('ROLE_PUREWEB_USER')"/>
    <s:intercept-url pattern="/pureweb/share/**" access="hasRole('ROLE_PUREWEB_USER')"/>
    -->
  3. Comment out the line containing access="hasAnyRole" and uncomment out the lines containing access=hasRole". The end result should look like this:

    <!-- pureweb collaboration -->
    <!-- Allow anonymous access to collaboration -->
    <!-- <s:intercept-url pattern="/pureweb/share" access="hasAnyRole('ROLE_PUREWEB_USER', 'ROLE_PUREWEB_COLLABORATOR')"/> -->
            
    <!-- Force ROLE_PUREWEB_USER access to collaboration (comment out line above) -->
    <s:intercept-url pattern="/pureweb/share" access="hasRole('ROLE_PUREWEB_USER')"/>
    <s:intercept-url pattern="/pureweb/share/**" access="hasRole('ROLE_PUREWEB_USER')"/>

Responding to Unauthorized Access

If an unauthorized user attempts to connect to a protected page, the server can respond in one of two ways:

  • Form-based authentication: the server will redirect unauthenticated clients to an authentication page to request the username and password. This is the recommended option and is selected by default.
  • Basic authentication: the server will report an HTTP 401 Unauthorized error to unauthenticated clients. If you are also using SSL, basic authentication may be sufficient.

To change the default response to unauthorized access, you edit the pureweb-context.xml file. You can access this file by logging into the server and clicking the Configuration link to open the Configuration page, or by navigating the server's file hierarchy to open it directly in a text editor. See General Configuration.

Once the file is open:

  1. Scroll down until you see the following section:
    <s:http auto-config="true" realm="PureWeb" createSession="always">
    <s:request-cache ref="requestCache"/>
    <!-- do not copy session attributes on authentication (in particular Client instances) -->
    <s:session-management session-fixation-protection="newSession"/>
    <!-- form-based authentication -->
    <s:form-login login-processing-url="/login"
        login-page="/pureweb/server/login.jsp"
        authentication-failure-ref="authenticationFailureHandler"
        default-target-url="/pureweb/server/status"
        always-use-default-target="false"/>
    <s:logout logout-url="/logout"
    logout-success-url="/pureweb/server/logout.jsp"/>
    <!-- basic authentication -->
    <!--
    <s:http-basic/>
    <s:logout logout-url="/logout"/>
    -->
    
  2. Comment out the form-based authentication section (lines 6 to 11) and remove comments for the basic authentication section (lines 13 and 16).