Container Authentication

Yana uses Spring-security for authentication and authorization. It is possible to use the web-application's container-level auth mechanisms to provide the username and authorized roles for the user to Spring-security.

The mechanism that Spring uses for this is called the "pre-authenticated" authentication provider. Spring will rely on the web-application container (such as Tomcat) to perform authentication and authorization, and will accept the result provided by the container rather than invoking any auth mechanisms itself.

This is useful if you need to integrate Yana with another authentication/authorization provider mechanism that Spring might not support, or for example if you wish to deploy it alongside other web-applications within a single container and use the same auth mechanisms for them.

Yana has been built to make this as easy as possible to enable.

Here are the steps to enable this form of authentication:

First: Follow the general deployment instructions, such as the Tomcat Deployment page.

2. Modify your yana-config.groovy configuration file to enable the "preAuthenticatedAuthenticationProvider" as your Spring authentication provider, and provide a mapping between your authentication-provider's "roles" and the internal Yana roleset.
3. Modify the WEB-INF/web.xml file for Yana inside the exploded webapp directory to add the appropriate security-constraints and login-config elements as required by the Servlet spec, which will tell your container when to require user authentication.
4. Finally, alter your container's configuration to define the necessary authentication/authorization mechanism, such as defining a Tomcat Realm within the server.xml or context.xml for Yana.

Modify yana-config.groovy

You must modify your yana-config.groovy file to enable the "preAuthenticatedAuthenticationProvider" as the Spring Security authentication provider.

Add the following line to yana-config.groovy:

//set the providerNames to include 'preAuthenticatedAuthenticationProvider'
grails.plugins.springsecurity.providerNames = ['preAuthenticatedAuthenticationProvider', 'anonymousAuthenticationProvider']

Role mapping

Since the authorization roles provided by the "external" mechanism will not necessarily be known to Spring-security, we have to provide it with a mapping of these external authentication provider role names to the internal roles used by Yana. Internally, Yana defines four roles.

• user access for role name ROLE_YANA_USER
• admin access for role name ROLE_YANA_ADMIN
• operator access for role name ROLE_YANA_OPERATOR
• architect access for role name ROLE_YANA_ARCHITECT
• superuser acccess for role name ROLE_YANA_SUPERUSER

(Note: if your authorization roles have the same names as the yana internal roles, you do not need to redefine the mapping.)

Your authorization mechanism (such as LDAP) may have different names for these roles, or you may just want to map them to other roles in your system.

You can define a mapping by setting properties of the "roleAuthorityMapper" bean in your yana-config.groovy.

You must define mappings for adminRole, operatorRole, architectRole and superuserRole.

//override role mapping values
beans {
    roleAuthorityMapper {
        adminRole=['admin','monkey']  // can use a list
        operatorRole='operator'  // or a comma-separated string
        architectRole='architect'     // or just a single value
        superuserRole='superuser'
        userRole='user' //read-only user role
    }
}

Here, the adminRole = <value> is a shortcut for setting the 'ROLE_YANA_ADMIN' role to be mapped to the "external" roles defined by <value>.

The value can be one of:

• A string name, e.g. 'myAdminRole'
• A string containing a list of names, separated by commas, e.g. 'role1,myAdminRole,role2' (do not include spaces)
• or a list defined like: ['role1','myAdminRole','role2']

This creates mappings for any external roles in the list to the appropriate Yana internal role, meaning that Users who have those external roles according to your authorization provider, will be known to Yana as having the corresponding access level.

Web app configuration

Since you are no longer using Spring security's login mechanism directly, you have to set up the web.xml for Yana to invoke the container's authentication system. The default web.xml contains most of the declarations needed for this, however you do need to add an <auth-constraint> to the appropriate section to enable it.

Add the Auth Constraint

Modify Yana's web.xml to add the following <auth-constraint> inside the <security-constraint> for the web-resource-name "web":

<security-constraint>
        <web-resource-collection>
            <web-resource-name>web</web-resource-name>
            <url-pattern>/*</url-pattern>
        </web-resource-collection>
        
        <!-- ADD this auth-constraint -->
        <auth-constraint>
            <role-name>yana</role-name>
        </auth-constraint>
       
        <user-data-constraint>
            <!-- if desired, require https via the transport-guarantee CONFIDENTIAL -->
            <transport-guarantee>CONFIDENTIAL</transport-guarantee>
        </user-data-constraint> 
</security-constraint>
<security-role>
    <description>This is the default role needed to access Yana</description>
    <role-name>yana</role-name>
</security-role>

All users that you want to give access to Yana must be in the role specified by the auth-constraint's role-name. The default is 'yana', but it can be any role name provided by your authorization system, just be sure to declare the role-name as a <security-role>.

If you want to allow multiple different roles to have access, add those role names as additional <security-role> entries, and either add a new <auth-constraint> for the second role, or change the <auth-constraint> role-name to "*" (asterisk) to indicate that any of the defined <security-role> role-names will be given access to the specified web-resource-collection.

Note: Since Tomcat will invoke the login page directly, Spring won't get a chance to redirect to HTTPS automatically. You must configure Tomcat to require HTTPS on the pages that you want to protect (ideally, all of them). Do this by setting the transport-guarantee to "CONFIDENTIAL" within this <security-constraint> element.

Tomcat configuration

To use container-authentication you must define the appropriate Authentication configuration for your container.

For Tomcat, make sure you define a Realm within your Tomcat server.xml or the appropriate context.xml. See the Tomcat Realm How-To.

The Realm will provide your users and roles .

Once you have configured your container's authentication, make sure your mapping in the yana-config.groovy correctly maps the roles (authorization) to the Yana internal role definitions.