LDSTechForumProjects

6.x Converting from v5.54 Config

A number of breaking API configuration changes were intentionally made when creating the 6.x line of the WAMulator in order to move to a format that can readily be exchanged between the WAMulator and OAM via Policy Exposee, the web tool used to manage OAM policies for applications. Most notably are the following which will play key roles in the steps to migrating below:

  • Replacement of the <users> element by one to many <user-source> elements of differing types including xml and LDAP.
  • Moving of the session-timeout-seconds attribute from <users> to <sso-cookie>.
  • Replacement of <sso-header> support at both the <user> declaration and global level with the concept of user attributes and new per <cctx-mapping> declarations of headers both fixed value and user profile attribute versions.
  • Addition of <by-site> matching properly being reliant upon protocol. Hence, if you are using <proxy-tls> to route both http and https through the wamulator, you could have different routing and enforcement per scheme. This would be unusual. More common is that both use the same routing and enforcment. but 6.x needs to know that the <by-site> directive matches on both if that is intended instead of only for 'http' which is the default. So add the scheme attribute accordingly to your <by-site> directives with value, http, https, or both as applicable.
  • Finally, condition syntax has changed removing all evaluators save for the logical combinators and the <Attribute> evaluator. See 6.x Condition Syntax for usage details.

A Sample 5.x Config File


Consider the following configuration file. First, note that all header names and user attributes used here are fictitious and meant solely to convey the point of there being user specific information had by users and leveraged by applications to provide their feature set to those users. What steps must we take to run in v6.x?

<?xml version="1.0" encoding="UTF-8"?>

<?alias rest-port=1776?>
<?alias console-port={{rest-port}}?>
<?alias http-port=80?>

<config proxy-port="{{http-port}}" console-port="auto" rest-version="CD-OESv1">

    <console-recording sso="true" rest="true" max-entries="100" enable-debug-logging='true'/>
    <sso-cookie name="ssoCookie-local" domain=".lds.org"/>
    <sso-header name="connection" value="close"/>

    <sso-traffic>
        <by-site host="new-local.lds.org" port="{{http-port}}">

            <cctx-mapping cctx="/platform*" thost="internal-dev-domain.net" tport="80" tpath="/platform-app*"/>

            <cctx-mapping cctx="/directory*" thost="127.0.0.1" tport="8080" tpath="/directory*"/>
            <allow action="GET,POST,PUT,DELETE" cpath="/directory/*"/>
            <allow action="GET,POST,PUT,DELETE" cpath="/directory/*?*"/>

            <cctx-mapping cctx="/church-calendar*" thost="127.0.0.1" tport="8080" tpath="/church-calendar*"/>
            <allow action="GET,POST,PUT,DELETE" cpath="/church-calendar/*"/>
            <allow action="GET,POST,PUT,DELETE" cpath="/church-calendar/*?*"/>

        </by-site>
    </sso-traffic>

    <users session-timeout-seconds='5000'>

        <user name="developer-aaa" pwd="password1">
            <sso-header name="sso-uid" value="84477"/>
            <sso-header name="sso-birthdate" value="19720630"/>
            <sso-header name="sso-prefname" value="Will A"/>
            <sso-header name="sso-sn" value="Anderson"/>
            <sso-header name="sso-mail" value="wa@someplace.com"/>
            <sso-header name="sso-preflang" value="en"/>
            <sso-header name="sso-unit" value="/7u2600/5u510000/"/>
            <sso-header name="sso-pos" value="p94/5u510000/1u790000/:p50/1u790000/:p1500/7u260000/5u510000/"/>
        </user>
        
        <!-- ... OTHER DEVELOPERS ... -->
        
        <!-- role specific test user -->
        <user name="ngiwb1" pwd="pass1">
            <sso-header name="sso-birthdate" value="1965-04-18"/>
            <sso-header name="sso-mail" value="ngiwb1@test.org"/>
            <sso-header name="sso-prefname" value="ngiWB1FirstName ngiWB1LastName"/>
            <sso-header name="sso-sn" value="ngiWB1LastName"/>
            <sso-header name="sso-uid" value="176600008"/>
            <sso-header name="sso-unit" value="/7u56000/5u520000/"/>
            <sso-header name="sso-pos" value="p44/7u56000/5u520000/"/>
            <sso-header name="sso-preflang" value="en"/>
        </user>

        <!-- ... OTHER ROLE SPECIFIC TEST USERS -->

        <user name="ngiwb2" pwd="pass2">
            <sso-header name="sso-birthdate" value="1965-03-27"/>
            <sso-header name="sso-mail" value="ngiwb2@test.org"/>
            <sso-header name="sso-prefname" value="ngiWB2FirstName ngiWB2LastName"/>
            <sso-header name="sso-sn" value="ngiWB2LastName"/>
            <sso-header name="sso-uid" value="18000082360"/>
            <sso-header name="sso-unit" value="/7u258000/5u520000/1u790000/"/>
            <sso-header name="sso-pos" value="p4/7u258000/5u520000/1u790000"/>
            <sso-header name="sso-preflang" value="en"/>
        </user>

    </users>
</config>


Moving session-timeout-seconds


The simplest change to make is moving the session-timeout-seconds from <users> which is not supported to its new home in <sso-cookie>.

<!-- so this old code -->
  <sso-cookie name="ssoCookie-local" domain=".lds.org"/>
  ...
  <users session-timeout-seconds='5000'>
  ...

<!-- becomes this -->
  <sso-cookie name="ssoCookie-local" domain=".lds.org" session-timeout-seconds='5000'/>
  ...
  <user-source type='xml'>
  ...

Moving Fixed Headers


Another straightforward change is dealing with fixed value headers. There are no <sso-header> declarations supported at the global level, ie: outside of <user> elements, so that connection close header must be moved. In actuality, that header is injected automatically and should be removed completely. But were there a need for a different fixed value header, we would add it as a <fixed-value> header within those <cctx-mapping> elements whose backing application needed to see that header.

For example note in the following contrived example that the /platform application has a different cctx path, the canonical context path as seen in the browser, than the path seen by its application server as portrayed by the cctx value being /platform and the tpath value being /platform-app. But suppose that it needed to be able to redirect to its own pages in some places. A fixed value header for just that application is a candidate solution. We can convey to the application where it resides in the canonical space and it can be crafted to redirect accordingly. Only that application will see that header injected to traffic proxied to its server.

<!-- old syntax -->
  <sso-header name="connection" value="close"/>
  ...
  <cctx-mapping cctx="/platform*" thost="internal-dev-domain.net" tport="80" tpath="/platform-app*"/>

<!-- new syntax -->
  <cctx-mapping cctx="/platform*" thost="internal-dev-domain.net" tport="80" tpath="/platform-app*">
    <headers>
      <fixed-value name='cctx' value='/platform'/>
      <!-- Note that the "connection close" header has been removed as it is injected automatically.-->
    </headers>
  </cctx-mapping>

Moving User Attribute Headers


Let us now turn our attention to user information. But before replacing the <users> element with <user-source> elements let's first adjust how user headers get injected. And for this discussion, let's suppose that the /directory and /church-calendar apps each use a different subset of the existing set of user headers being injected. In v5.x and lower versions there was no way to split up user headers. If any application needed a header all users got it and it went to all applications.

In v6.x we can now segregate them. Now, attributes are the only thing that gets injected into user objects in the WAMulator. Then, on a per application basis (i.e., a per cctx-mapping basis) we selectively inject only those headers needed by that application.

Note that <profile-att>'s attribute value must match some attribute of the user for that header to be injected. If no attribute is found then that header won't be injected although any existing such header coming from the client's browser will be scrubbed from the request. Further, note that not all user attributes are being used. Ostensibly, some other app must be using them if they are included in the config file.

<!-- so this old syntax -->
  <cctx-mapping cctx="/directory*" thost="127.0.0.1" tport="8080" tpath="/directory*"/>
  ...
  <cctx-mapping cctx="/church-calendar*" thost="127.0.0.1" tport="8080" tpath="/church-calendar*"/>
  ...
  <user name="dev-user" pwd="password1">
    <sso-header name="sso-uid"       value="84477"/>
    <sso-header name="sso-birthdate" value="19720630"/>
    <sso-header name="sso-prefname"  value="Will A"/>
    <sso-header name="sso-sn"        value="Anderson"/>
    <sso-header name="sso-mail"      value="wa@someplace.com"/>
    <sso-header name="sso-preflang"  value="en"/>
    <sso-header name="sso-unit"      value="/7u2600/5u510000/"/>
    <sso-header name="sso-pos"       value="p94/5u510000/1u790000/:p50/1u790000/:p1500/7u260000/5u510000/"/>
  </user>

<!-- becomes this new syntax -->
  <cctx-mapping cctx="/directory*" thost="127.0.0.1" tport="8080" tpath="/directory*">
    <headers>
      <profile-att name='sso-uid'       attribute='uid'/>
      <profile-att name='sso-birthdate' attribute='birthdate'/>
      <profile-att name='sso-prefname'  attribute='prefname'/>
      <profile-att name='sso-pos'       attribute='pos'/>
    </headers>
  </cctx-mapping>
  ...
  <cctx-mapping cctx="/church-calendar*" thost="127.0.0.1" tport="8080" tpath="/church-calendar*">
    <headers>
      <profile-att name='sso-uid'  attribute='uid'/>
      <profile-att name='sso-sn'   attribute='sn'/>
      <profile-att name='sso-unit' attribute='unit'/>
      <profile-att name='sso-mail' attribute='mail'/>
    </headers>
  </cctx-mapping>
  ...
  <user name="dev-user" pwd="password1">
    <att name="uid"       value="84477"/>
    <att name="birthdate" value="19720630"/>
    <att name="prefname"  value="Will A"/>
    <att name="sn"        value="Anderson"/>
    <att name="mail"      value="wa@someplace.com"/>
    <att name="preflang"  value="en"/>
    <att name="unit"      value="/7u2600/5u510000/"/>
    <att name="pos"       value="p94/5u510000/1u790000/:p50/1u790000/:p1500/7u260000/5u510000/"/>
  </user>

Moving <users> to <user-source>

But lets make our example more meaningful. Let's suppose that the users in the file fall into two groups, developer users that reflect real data for members of the development and test teams and fictitious test accounts with contrived data to simulate various groups who should observe specific features of the application. That first group raises a concern. Such a file should not be checked into the source code repository for all to see while the second readily could be. So in our V6.0 configuration we'll split those two up and have the behavior gracefully drop the first set if not found when starting up. (Alternatively, take a look at an example that embeds user information directly into the config file via aliases.)

To implement this two file approach, we will leverage two features of configuration, the <?file-alias?> or <?classpath-alias?> directives and the fact that <user-source> content uses simple-line Properties file format with support of alias macro resolution.

First, we'll place our test users in a file in the project's test/resources area so that it will be avialable via the classpath and then declare a <?classpath-alias?> to it like so. Note that there is no need for a default for that alias since we intend to check it in with the project.

Alias Declaration

<!-- so this old code -->
<?classpath-alias test-user-xml="test-users.xml"?>

Test File Contents:

    <users>
        <!-- role specific test user -->
        <user name="test-user" pwd="pass1">
           <att name="uid"       value="176600008"/>
           <att name="birthdate" value="19650418"/>
           <att name="prefname"  value="ngiWB1FirstName ngiWB1LastName"/>
           <att name="sn"        value="ngiWB1LastName"/>
           <att name="mail"      value="ngiwb1@test.org"/>
           <att name="preflang"  value="en"/>
           <att name="unit"      value="/7u56000/5u520000/"/>
           <att name="pos"       value="p44/7u56000/5u520000/"/>
        </user>

        <!-- ... OTHER ROLE SPECIFIC TEST USERS -->

    </users>

Next we declare a <?file-alias?> with a path to the file external to the application but with a default value having the empty <users/> element in case the file is not found and add the sensitive user information there.

Alias Declaration

<!-- so this old code -->
<?file-alias dev-user-xml="c:/some/path/dev-users.xml" default="<users/>"?>

Test File Contents:

    <users>
        <!-- role specific test user -->
        <user name="dev-user" pwd="password1">
           <att name="uid"       value="84477"/>
           <att name="birthdate" value="19720630"/>
           <att name="prefname"  value="Will A"/>
           <att name="sn"        value="Anderson"/>
           <att name="mail"      value="wa@someplace.com"/>
           <att name="preflang"  value="en"/>
           <att name="unit"      value="/7u2600/5u510000/"/>
           <att name="pos"       value="p94/5u510000/1u790000/:p50/1u790000/:p1500/7u260000/5u510000/"/>
        </user>

        <!-- ... OTHER DEVELOPERS ... -->

    </users>

With these aliases in place we can now declare our XML user sources.

    <user-source type='xml'>xml={{dev-user-xml}}</user-source>
    <user-source type='xml'>xml={{test-user-xml}}</user-source>

Now, upon firing up when the c:/some/path/dev-users.xml file is not found I see only the test-user in my simulator's Users & Sessions tab. When the file is found I see both users.

Test User only appear Test and Dev Users appear

The Complete 6.x Config File

<?xml version="1.0" encoding="UTF-8"?>

<?alias rest-port=1776?>
<?alias console-port={{rest-port}}?>
<?alias http-port=80?>

<?classpath-alias test-user-xml="test-users.xml"?>
<?file-alias dev-user-xml="c:/some/path/dev-users.xml" default="<users/>"?>

<config proxy-port="{{http-port}}" console-port="auto" rest-version="CD-OESv1">
    <console-recording sso="true" rest="true" max-entries="100" enable-debug-logging='true'/>
    <sso-cookie name="ssoCookie-local" domain=".lds.org" session-timeout-seconds='5000'/>

    <sso-traffic>
        <by-site host="new-local.lds.org" port="{{http-port}}">
 
            <cctx-mapping cctx="/platform*" thost="internal-dev-domain.net" tport="80" tpath="/platform-app*">
                <headers>
                  <fixed-value name='cctx' value='/platform'/>
                </headers>
            </cctx-mapping>

            <cctx-mapping cctx="/directory*" thost="127.0.0.1" tport="8080" tpath="/directory*">
              <headers>
                <profile-att name='sso-uid'       attribute='uid'/>
                <profile-att name='sso-birthdate' attribute='birthdate'/>
                <profile-att name='sso-prefname'  attribute='prefname'/>
                <profile-att name='sso-pos'       attribute='pos'/>
              </headers>
            </cctx-mapping>
            <allow action="GET,POST,PUT,DELETE" cpath="/directory/*"/>
            <allow action="GET,POST,PUT,DELETE" cpath="/directory/*?*"/>

            <cctx-mapping cctx="/church-calendar*" thost="127.0.0.1" tport="8080" tpath="/church-calendar*">
              <headers>
                <profile-att name='sso-uid'  attribute='uid'/>
                <profile-att name='sso-sn'   attribute='sn'/>
                <profile-att name='sso-unit' attribute='unit'/>
                <profile-att name='sso-mail' attribute='mail'/>
              </headers>
            </cctx-mapping>
            <allow action="GET,POST,PUT,DELETE" cpath="/church-calendar/*"/>
            <allow action="GET,POST,PUT,DELETE" cpath="/church-calendar/*?*"/>

        </by-site>
    </sso-traffic>

    <user-source type='xml'>xml={{dev-user-xml}}</user-source>
    <user-source type='xml'>xml={{test-user-xml}}</user-source>
</config>
This page was last modified on 2 December 2016, at 13:04.

Note: Content found in this wiki may not always reflect official Church information. See Terms of Use.