<commit_before><?xml version="1.0" encoding="UTF-8"?>
<!--
  ~ This is part of Geomajas, a GIS framework, http://www.geomajas.org/.
  ~
  ~ Copyright 2008-2012 Geosparc nv, http://www.geosparc.com/, Belgium.
  ~
  ~ The program is available in open source according to the GNU Affero
  ~ General Public License. All contributions in this program are covered
  ~ by the Geomajas Contributors License Agreement. For full licensing
  ~ details, see LICENSE.txt in the project root.
  -->
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<chapter id="chapter-howto">
  <title>How-to</title>

  <para></para>

  <section id="howto-custom-policies">
    <title>Add custom policies with a custom SecurityContext</title>

    <para>To add custom policies in the security context, you need the
    following steps:</para>

    <itemizedlist>
      <listitem>
        <para>Define your custom policy.</para>
      </listitem>

      <listitem>
        <para>Provide an implementation for your custom policy.</para>
      </listitem>

      <listitem>
        <para>Build a security context which can combine different
        authorizations which contain the new policy.</para>
      </listitem>

      <listitem>
        <para>Build a security manager which uses the new security
        context.</para>
      </listitem>

      <listitem>
        <para>Wire it all together.</para>
      </listitem>
    </itemizedlist>

    <para>Let's go over this using a practical example. In our example
    application, we want a "blabla" button which should not be visible to all
    users.</para>

    <para>The way it is handled here allows you to query the new policy using
    your autowired security context.</para>

    <informalexample>
      <programlisting>@Autowired
private AppSecurityContext securityContext</programlisting>
    </informalexample>

    <section id="howto-cp-define">
      <title>Define your policy</title>

      <para>You always have to define your policy in as an interface which
      extends BaseAuthorization. This is the base interface for all types of
      authorization objects. As you extend BaseAuthorization, you will always
      have to include handling of basic security on layers.</para>

      <para>We just want to add a method to determine if using the "blabla"
      button is allowed.</para>

      <xi:include href="listing/AppAuthorization.xml"
                  xmlns:xi="http://www.w3.org/2001/XInclude" />
    </section>

    <section id="howto-cp-impl">
      <title>Implement your policy</title>

      <para>To be able to implement our new authorization object we also need
      to provide a way to configure the value for specific users or roles. For
      this example, we build on the layer configuration object which is
      provided by the staticsecurity plug-in.</para>

      <para>Apart from the methods which are used to get and set the extra
      values in the configuration, there is also a getAuthorizaton() method
      which is overwritten. This is used by the staticsecurity security
      service to build the actual authorization objects from the
      configuration.</para>

      <xi:include href="listing/AppAuthorizationInfo.xml"
                  xmlns:xi="http://www.w3.org/2001/XInclude" />

      <para>The actual implementation is quite easy on our case. Just use the
      configuration object to return the correct value for the new
      policy.</para>

      <para>It is important to have a no-args constructor in this class as it
      is needed to deserialize the authorization when needed (which is for
      example used in rasterizing).</para>

      <xi:include href="listing/AppAuthorizationImpl.xml"
                  xmlns:xi="http://www.w3.org/2001/XInclude" />
    </section>

    <section id="howto-cp-context">
      <title>Build your security context</title>

      <para>We need to build a new security context implementation which also
      handles our additional policy. We do this by extending the default
      implementation. Note that you need to add geomajas-impl as a project
      dependency to compile this (but rest assured, being able to extend
      DefaultSecurityContext is assured by the API contract).</para>

      <xi:include href="listing/AppSecurityContext.xml"
                  xmlns:xi="http://www.w3.org/2001/XInclude" />
    </section>

    <section id="howto-cp-manager">
      <title>Build your security manager</title>

      <para>The security context is created and set by the security manager,
      so you also have to replace the security manager to make sure it uses
      your security context.</para>

      <xi:include href="listing/AppSecurityManager.xml"
                  xmlns:xi="http://www.w3.org/2001/XInclude" />
    </section>

    <section id="howto-cp-wire">
      <title>Wire it together</title>

      <para>You have to make sure that spring known about your new security
      manager and context. You can do this by including the following excerpt
      in your application context. It is very important to include the scope
      and scoped-proxy bits in the security context declaration. That
      annotations which are included on the class are not used when using the
      bean style declaration, so you have to add them explicitly. If you
      forget this, you will get spurious errors using the wrong
      context.</para>

      <xi:include href="listing/ReplaceSecurityContext.xml"
                  xmlns:xi="http://www.w3.org/2001/XInclude" />

      <para>You can create a configuration which uses your new policy.</para>

      <xi:include href="listing/CustomPolicyUse.xml"
                  xmlns:xi="http://www.w3.org/2001/XInclude" />
    </section>
  </section>

  <section id="howto-custom-policy-client">
    <title>Using a custom policy client-side</title>

    <para>If you want to have access to some of your custom policies on the
    client side, then you have to get these from the server on startup.</para>

    <para>The best way to handle this is to replace the command to get the
    initial configuration with a version which also includes your policy. Then
    on the response you can set the policy in a class to allow you to access
    the information.</para>

    <para>For starters, let's create the client security context class. This
    is a static class which just contains accessors for the
    blablaButtonAllowed property.</para>

    <xi:include href="listing/ClientSecurityContext.xml"
                xmlns:xi="http://www.w3.org/2001/XInclude" />

    <para>The value will be set when the configuration is read. This is
    automatically re-read when the security token changes. The advantage of
    combining this with the get configuration command is that only one command
    needs to be called. Use code like the following in your entry point class
    before the map widget is created.</para>

    <xi:include href="listing/ClientConfigurationLoader.xml"
                xmlns:xi="http://www.w3.org/2001/XInclude" />

    <para>This snippet uses a custom command which extends the standard
    GetConfigurationCommand. The code is shown below.</para>

    <xi:include href="listing/AppConfigurationCommand.xml"
                xmlns:xi="http://www.w3.org/2001/XInclude" />

    <para>The request and response objects also need to be redefined for this
    command. For the request object this is almost trivial. The most important
    change is to overwrite the COMMAND field.</para>

    <xi:include href="listing/AppConfigurationRequest.xml"
                xmlns:xi="http://www.w3.org/2001/XInclude" />

    <para>The response object needs some extra extensions to ensure that the
    custom policy information is included.</para>

    <xi:include href="listing/AppConfigurationResponse.xml"
                xmlns:xi="http://www.w3.org/2001/XInclude" />

    <para>You can see this in action in the example application.</para>
  </section>
</chapter><commit_msg>SSEC-31 document how to change order of evaluation of configured "users"<commit_after><?xml version="1.0" encoding="UTF-8"?>
<!--
  ~ This is part of Geomajas, a GIS framework, http://www.geomajas.org/.
  ~
  ~ Copyright 2008-2012 Geosparc nv, http://www.geosparc.com/, Belgium.
  ~
  ~ The program is available in open source according to the GNU Affero
  ~ General Public License. All contributions in this program are covered
  ~ by the Geomajas Contributors License Agreement. For full licensing
  ~ details, see LICENSE.txt in the project root.
  -->
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<chapter id="chapter-howto">
  <title>How-to</title>

  <para></para>

  <section id="howto-custom-policies">
    <title>Add custom policies with a custom SecurityContext</title>

    <para>To add custom policies in the security context, you need the
    following steps:</para>

    <itemizedlist>
      <listitem>
        <para>Define your custom policy.</para>
      </listitem>

      <listitem>
        <para>Provide an implementation for your custom policy.</para>
      </listitem>

      <listitem>
        <para>Build a security context which can combine different
        authorizations which contain the new policy.</para>
      </listitem>

      <listitem>
        <para>Build a security manager which uses the new security
        context.</para>
      </listitem>

      <listitem>
        <para>Wire it all together.</para>
      </listitem>
    </itemizedlist>

    <para>Let's go over this using a practical example. In our example
    application, we want a "blabla" button which should not be visible to all
    users.</para>

    <para>The way it is handled here allows you to query the new policy using
    your autowired security context.</para>

    <informalexample>
      <programlisting>@Autowired
private AppSecurityContext securityContext</programlisting>
    </informalexample>

    <section id="howto-cp-define">
      <title>Define your policy</title>

      <para>You always have to define your policy in as an interface which
      extends BaseAuthorization. This is the base interface for all types of
      authorization objects. As you extend BaseAuthorization, you will always
      have to include handling of basic security on layers.</para>

      <para>We just want to add a method to determine if using the "blabla"
      button is allowed.</para>

      <xi:include href="listing/AppAuthorization.xml"
                  xmlns:xi="http://www.w3.org/2001/XInclude" />
    </section>

    <section id="howto-cp-impl">
      <title>Implement your policy</title>

      <para>To be able to implement our new authorization object we also need
      to provide a way to configure the value for specific users or roles. For
      this example, we build on the layer configuration object which is
      provided by the staticsecurity plug-in.</para>

      <para>Apart from the methods which are used to get and set the extra
      values in the configuration, there is also a getAuthorizaton() method
      which is overwritten. This is used by the staticsecurity security
      service to build the actual authorization objects from the
      configuration.</para>

      <xi:include href="listing/AppAuthorizationInfo.xml"
                  xmlns:xi="http://www.w3.org/2001/XInclude" />

      <para>The actual implementation is quite easy on our case. Just use the
      configuration object to return the correct value for the new
      policy.</para>

      <para>It is important to have a no-args constructor in this class as it
      is needed to deserialize the authorization when needed (which is for
      example used in rasterizing).</para>

      <xi:include href="listing/AppAuthorizationImpl.xml"
                  xmlns:xi="http://www.w3.org/2001/XInclude" />
    </section>

    <section id="howto-cp-context">
      <title>Build your security context</title>

      <para>We need to build a new security context implementation which also
      handles our additional policy. We do this by extending the default
      implementation. Note that you need to add geomajas-impl as a project
      dependency to compile this (but rest assured, being able to extend
      DefaultSecurityContext is assured by the API contract).</para>

      <xi:include href="listing/AppSecurityContext.xml"
                  xmlns:xi="http://www.w3.org/2001/XInclude" />
    </section>

    <section id="howto-cp-manager">
      <title>Build your security manager</title>

      <para>The security context is created and set by the security manager,
      so you also have to replace the security manager to make sure it uses
      your security context.</para>

      <xi:include href="listing/AppSecurityManager.xml"
                  xmlns:xi="http://www.w3.org/2001/XInclude" />
    </section>

    <section id="howto-cp-wire">
      <title>Wire it together</title>

      <para>You have to make sure that spring known about your new security
      manager and context. You can do this by including the following excerpt
      in your application context. It is very important to include the scope
      and scoped-proxy bits in the security context declaration. That
      annotations which are included on the class are not used when using the
      bean style declaration, so you have to add them explicitly. If you
      forget this, you will get spurious errors using the wrong
      context.</para>

      <xi:include href="listing/ReplaceSecurityContext.xml"
                  xmlns:xi="http://www.w3.org/2001/XInclude" />

      <para>You can create a configuration which uses your new policy.</para>

      <xi:include href="listing/CustomPolicyUse.xml"
                  xmlns:xi="http://www.w3.org/2001/XInclude" />
    </section>
  </section>

  <section id="howto-custom-policy-client">
    <title>Using a custom policy client-side</title>

    <para>If you want to have access to some of your custom policies on the
    client side, then you have to get these from the server on startup.</para>

    <para>The best way to handle this is to replace the command to get the
    initial configuration with a version which also includes your policy. Then
    on the response you can set the policy in a class to allow you to access
    the information.</para>

    <para>For starters, let's create the client security context class. This
    is a static class which just contains accessors for the
    blablaButtonAllowed property.</para>

    <xi:include href="listing/ClientSecurityContext.xml"
                xmlns:xi="http://www.w3.org/2001/XInclude" />

    <para>The value will be set when the configuration is read. This is
    automatically re-read when the security token changes. The advantage of
    combining this with the get configuration command is that only one command
    needs to be called. Use code like the following in your entry point class
    before the map widget is created.</para>

    <xi:include href="listing/ClientConfigurationLoader.xml"
                xmlns:xi="http://www.w3.org/2001/XInclude" />

    <para>This snippet uses a custom command which extends the standard
    GetConfigurationCommand. The code is shown below.</para>

    <xi:include href="listing/AppConfigurationCommand.xml"
                xmlns:xi="http://www.w3.org/2001/XInclude" />

    <para>The request and response objects also need to be redefined for this
    command. For the request object this is almost trivial. The most important
    change is to overwrite the COMMAND field.</para>

    <xi:include href="listing/AppConfigurationRequest.xml"
                xmlns:xi="http://www.w3.org/2001/XInclude" />

    <para>The response object needs some extra extensions to ensure that the
    custom policy information is included.</para>

    <xi:include href="listing/AppConfigurationResponse.xml"
                xmlns:xi="http://www.w3.org/2001/XInclude" />

    <para>You can see this in action in the example application.</para>
  </section>

  <section>
    <title>Evaluating directly configured users first</title>

    <para>Normal behavior is that the users which a directly configured in the
    SecurityServiceInfo object users field are searched after the services
    which are configured in the authenticationServices field. This can be very
    useful for testing, for example when the remote service is not available
    (and the system waits for times). This can be changed by using a
    configuration like</para>

    <example>
      <title>Evaluating configured users first</title>

      <programlisting>&lt;bean class="org.geomajas.plugin.staticsecurity.configuration.SecurityServiceInfo"&gt;
    &lt;!-- LDAP authentication AFTER configured users --&gt;
    &lt;property name="authenticationServices"&gt;
        &lt;list&gt;
            &lt;bean class="org.geomajas.plugin.staticsecurity.security.StaticAuthenticationService" /&gt;
            &lt;bean class="org.geomajas.plugin.staticsecurity.ldap.LdapAuthenticationService"&gt;
                &lt;!-- ..... LDAP settings --&gt;
            &lt;/bean&gt;
        &lt;/list&gt;
    &lt;/property&gt;
&lt;/bean&gt;</programlisting>
    </example>
  </section>
</chapter>
{'fraction_non_alphanumeric': 0.08751660793714978, 'fraction_numerical': 0.008780544162671135, 'mean_word_length': 2.9552204706419922, 'pattern_counts': {'":': 0, '<': 249, '<?xml version=': 2, '>': 249, 'https://': 0, 'lorem ipsum': 0, 'www.': 30, 'xml': 52}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5565037', 'n_tokens_mistral': 4790, 'n_tokens_neox': 4496, 'n_words': 1806}