spring-security/src/docbkx/runas-auth-provider.xml

<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="runas"><info><title>Run-As Authentication Replacement</title></info>
    
    
    <section xml:id="runas-overview"><info><title>Overview</title></info>
        
        
        <para>The <literal>AbstractSecurityInterceptor</literal> is able to
            temporarily replace the <literal>Authentication</literal> object in
            the <literal>SecurityContext</literal> and
            <literal>SecurityContextHolder</literal> during the secure object
            callback phase. This only occurs if the original
            <literal>Authentication</literal> object was successfully processed by
            the <literal>AuthenticationManager</literal> and
            <literal>AccessDecisionManager</literal>. The
            <literal>RunAsManager</literal> will indicate the replacement
            <literal>Authentication</literal> object, if any, that should be used
            during the <literal>SecurityInterceptorCallback</literal>.</para>
        
        <para>By temporarily replacing the <literal>Authentication</literal>
            object during the secure object callback phase, the secured invocation
            will be able to call other objects which require different
            authentication and authorization credentials. It will also be able to
            perform any internal security checks for specific
            <literal>GrantedAuthority</literal> objects. Because Spring Security
            provides a number of helper classes that automatically configure
            remoting protocols based on the contents of the
            <literal>SecurityContextHolder</literal>, these run-as replacements
            are particularly useful when calling remote web services</para>
    </section>
    
    <section xml:id="runas-config"><info><title>Configuration</title></info>
        
        
        <para>A <literal>RunAsManager</literal> interface is provided by Acegi
            Security:</para>
        
        <para><programlisting>public Authentication buildRunAs(Authentication authentication, Object object, ConfigAttributeDefinition config);
            public boolean supports(ConfigAttribute attribute);
            public boolean supports(Class clazz);</programlisting></para>
        
        <para>The first method returns the <literal>Authentication</literal>
            object that should replace the existing
            <literal>Authentication</literal> object for the duration of the
            method invocation. If the method returns <literal>null</literal>, it
            indicates no replacement should be made. The second method is used by
            the <literal>AbstractSecurityInterceptor</literal> as part of its
            startup validation of configuration attributes. The
            <literal>supports(Class)</literal> method is called by a security
            interceptor implementation to ensure the configured
            <literal>RunAsManager</literal> supports the type of secure object
            that the security interceptor will present.</para>
        
        <para>One concrete implementation of a <literal>RunAsManager</literal>
            is provided with Spring Security. The
            <literal>RunAsManagerImpl</literal> class returns a replacement
            <literal>RunAsUserToken</literal> if any
            <literal>ConfigAttribute</literal> starts with
            <literal>RUN_AS_</literal>. If any such
            <literal>ConfigAttribute</literal> is found, the replacement
            <literal>RunAsUserToken</literal> will contain the same principal,
            credentials and granted authorities as the original
            <literal>Authentication</literal> object, along with a new
            <literal>GrantedAuthorityImpl</literal> for each
            <literal>RUN_AS_</literal> <literal>ConfigAttribute</literal>. Each
            new <literal>GrantedAuthorityImpl</literal> will be prefixed with
            <literal>ROLE_</literal>, followed by the <literal>RUN_AS</literal>
            <literal>ConfigAttribute</literal>. For example, a
            <literal>RUN_AS_SERVER</literal> will result in the replacement
            <literal>RunAsUserToken</literal> containing a
            <literal>ROLE_RUN_AS_SERVER</literal> granted authority.</para>
        
        <para>The replacement <literal>RunAsUserToken</literal> is just like
            any other <literal>Authentication</literal> object. It needs to be
            authenticated by the <literal>AuthenticationManager</literal>,
            probably via delegation to a suitable
            <literal>AuthenticationProvider</literal>. The
            <literal>RunAsImplAuthenticationProvider</literal> performs such
            authentication. It simply accepts as valid any
            <literal>RunAsUserToken</literal> presented.</para>
        
        <para>To ensure malicious code does not create a
            <literal>RunAsUserToken</literal> and present it for guaranteed
            acceptance by the <literal>RunAsImplAuthenticationProvider</literal>,
            the hash of a key is stored in all generated tokens. The
            <literal>RunAsManagerImpl</literal> and
            <literal>RunAsImplAuthenticationProvider</literal> is created in the
            bean context with the same key:</para>
        
        <para><programlisting>
            &lt;bean id="runAsManager" class="org.springframework.security.runas.RunAsManagerImpl"&gt;
            &lt;property name="key"&gt;&lt;value&gt;my_run_as_password&lt;/value&gt;&lt;/property&gt;
            &lt;/bean&gt;
            
            &lt;bean id="runAsAuthenticationProvider"
            class="org.springframework.security.runas.RunAsImplAuthenticationProvider"&gt;
            &lt;property name="key"&gt;&lt;value&gt;my_run_as_password&lt;/value&gt;&lt;/property&gt;
            &lt;/bean&gt;
            
        </programlisting></para>
        
        <para>By using the same key, each <literal>RunAsUserToken</literal>
            can be validated it was created by an approved
            <literal>RunAsManagerImpl</literal>. The
            <literal>RunAsUserToken</literal> is immutable after creation for
            security reasons</para>
    </section>
</chapter>