The asfs.xml configuration file contains one required section and five optional sections.

/configuration/accounts/account/username (required section)

This is a minimal configuration that would allow ANY user authenticated at the identity provider as a SharePoint user with account name set to a static value “SomeUser”. This is not very useful for most scenarios.

<configuration>
  <accounts>
    <account>
      <username value="SomeUser"/>
    </account>
  </accounts>
</configuration>

Here is the accounts section with comments.

<configuration>
  <accounts match="<order>">
    <account conditionId="<id>" doGroup="<bool>" doProfile="<bool>">
      <username value="<template>"/>
      <email value="<template>"/>
      <displayname value=<template>"/>
    </account>
  </accounts>
</configuration>

The accounts[@match] attribute is optional and defaults to “first”. If you set it to match=”last”, the order of matching will start with the bottom. The first matching account rule will execute.

The conditionId is optional. If provided, the corresponding condition must evaluate to true for the account rule to execute. If not provided, the account rule will execute.

The doGroup and doProfile are optional and defaults to “true”. If you set them to “false”, group mapping and profile mapping will be disabled for that user, even if there are group rules or profile rules with conditions evaluating to true. These will override them.

The username element is required. The email and displayname are optional. If the email element is present, it will use the value to populate the SharePoint principal’s email field. Likewise for displayname. The value of <template> can be any string value. It can contain variables that correspond to the id of serverVariables. For example, if value=”User $uid$”, and the user’s uid attribute contained “testuser”, then the SharePoint account name would be set to “User testuser”:

<serverVariables>
  <serverVariable id="uid" name="HTTP_UID"/>
<serverVariables> 

<accounts>
  <account>
    <username value="User $uid$"/>
  </account>
</accounts>

/configuration/serverVariables/serverVariable (optional section)

To make use of SAML attributes, you must have the serverVariables section present.

<configuration>
  <serverVariables>
    <serverVariable id="uid" name="HTTP_UID"/>
  </serverVariables>

  <accounts>
    <account>
      <username value="$uid$"/>
    </account>
  </accounts>
</configuration>

/configuration/conditions/condition (optional section)

Conditions are used to allow certain rules to run depending on values in the server variables. Within a condition, you can combine expressions with “or”, “and”, “(“, “)”, and also negate them using “!”. Below, there are specific rules for users that run depending on what values are present in the server variables. Notice that there is an account rule with no conditionId at the end.

<configuration>
  <serverVariables>
    <serverVariable id="uid" name="HTTP_UID"/>
    <serverVariable id="email" name="HTTP_EMAIL"/>
  </serverVariables>

  <conditions>
    <condition id="user1">
      uid=="user1" or email~="user1@example.com"
    </condition>
    <condition id="user2">
      uid~="User2" and email~="user2@example.com"
    </condition>
  </condition>

  <accounts>
    <account conditionId="user1">
      <username value="$uid$"/>
      <displayname value="USER ONE"/>
    </account>
    <account conditionId="user2">
      <username value="$uid$"/>
      <email value="$email$"/>
    </account>
    <account>
      <username value="$uid$"/>
    </account>
  </accounts>
</configuration>

/configuration/roles/role (optional section)

Roles are used to map values to the SharePoint user’s role.

<configuration>
  ...
  <roles match="<order>">
    <role conditionId="<id>" value="<template>"/>
  </roles>
</configuration>

The match attribute is optional and defaults to “all”. <order> can take on values: “first”, “last”, or “all”.

The conditionId is optional. If there is no conditionId, then the role rule executes as if the condition evaluated to “true”.

The <template> value can be any string. If it contains variables, and the variable corresponds to a multi-valued attribute, it will create multiple roles for the user using each value in the multi-valued attribute.

/configuration/groups/group (optional section)

This is used to add users to SharePoint security groups on-the-fly.

<configuration>
  ...
  <groups match="<order>">
    <group conditionId="<id>" relativeUrl="<path>" name="<sharepointgroupname>"/>
  </groups>
</configuration>

The match attribute is optional and defaults to “all”. <order> can take on values: “first”, “last”, or “all”.

The conditionId is optional. If there is no conditionId, then the group rule executes as if the condition evaluated to “true”.

The <path> value must correspond to a site collection path. For example, the root site collection path would be “/”. If you have additional site collections under /sites/mysc1, then the relativeUrl should be set to “/sites/mysc1”.

The <sharepointgroupname> value should match an existing SharePoint security group name within the site collection specified by the relativeUrl.

/configuration/profiles/profile (optional section)

This is used to add/update user profile properties on-the-fly when users login. Your SharePoint Server will need to have the User Profile Service running for this to work.

<configuration>
  ...
  <profiles match="<order>">
    <profile conditionId="<id>" property="<profilepropertyname>" value="<template>" overwrite="<bool>"/>
  </profiles>
</configuration>

The match attribute is optional and defaults to “all”. <order> can take on values: “first”, “last”, or “all”.

The conditionId is optional. If there is no conditionId, then the profile rule executes as if the condition evaluated to “true”.

The <profilepropertyname> should match a profile property name that exists in the User Profile Service.

The overwrite attribute is optional and defaults to “false”. This means that the profile property will be written to only if it is empty. If set to true, the profile property will be overwritten on each login.