Default Namespace Policy Example

A default namespace is similar to a home directory in a file system. Users are automatically given a default namespace under "/sandbox/". You can use the defaultNamespace claim to set the default namespace for individual users, or use the defaultNamespacePrefix claim to define a namespace prefix that is applied to all users.

Example: Set default namespace for each user

You can set the default namespace for a user with policy. For such policy, the Auth Server issues the claim type defaultNamespace and the value is a namespace.

In this example, the defaultNamespace is set by the Auth Server using a specific string corresponding to the user.

auth::/ {
  if (auth_server@apcera.me->name == "tom") {
    defaultNamespace "/demos/tom"
  }
}

Example: Override the default "/sandbox/" namespace path

To use default namespace paths other than /sandbox/, rather than setting the defaultNamespace for each user individually, you can set the defaultNamespacePrefix claim. For each authenticated user, their sandbox namespace will be composed of the specified prefix followed by the users's principal-name.

For instance, in the following example the defaultNamespacePrefix claim is set to users/ globally. If the authenticating user's email address is tom.smith@example.com their default namespace will be /users/tom.smith.

auth::/ {
{ 
    defaultNamespacePrefix "users/" }
}

In the following example, different prefixes are used based on which authentication mechanism was used to log in. If the authenticating user's Google authentication principal is tom.smith@example.com their default namespace will be /sandbox/googleauth.tom.smith (note that a slash is not automatically appended to the prefix value).

auth::/ {
  if (auth_server@apcera.me->authType == LDAPBasic) {
     defaultNamespacePrefix "/sandbox/ldapauth."
  }
  if (auth_server@apcera.me->authType == Google) {
     defaultNamespacePrefix "/sandbox/googlauth."
  }
}

Anticipating and fixing problems with default namespaces

For cases where the defaultNamespace claim type is not defined, the basis for the principal-name is the auth_server@apcera.me->name value (with the exception of the LDAP authentication - see below). If the value has the format of an email address such as "admin@apcera.me" then the is the local-part resulting in "/sandbox/admin". Otherwise if name is not an email address then principal-name is the full `auth_server@apcera.me->name`. This automatic behavior means that the value must not contain spaces and most punctuation characters because the namespace string must comply with FQN syntax rules.

If the defaultNamespacePrefix is specified a special feature is enabled that "scrubs" the auth_server@apcera.me->name value to produce a principal-name without spaces and most punctuation converted to underlines (_). For example, a name claim of r. joe (bob) doe@down.home becomes /PREFIX/r.joe_bob_doe. The three punctuation characters which are allowed in a namespace are dashes -, periods . and underlines _. On the other hand, if no defaultNamespacePrefix claim is provided, then that example name claim results in an error that spaces are not allowed in an FQN.

You may enable scrubbing of the principal-name but still maintain the built-in placement of namespaces under /sandbox/ with the following policy.

auth::/ {
  { defaultNamespacePrefix "/sandbox/" }
}

Enhanced namespace features available with LDAP authentication

When using LDAP authentication, the server may be configured to map any user attribute to the relativeNamespace claim which is used as the basis for principal-name. When the relativeNamespace claim is defined, its value is always "scrubbed" as decribed above, regardless of whether a defaultNamespacePrefix is provided or not. The out-of-box configuration for ActiveDirectory sets this value to the sAMAccountName (AD Model) or userPrincipalName (ADMulti model). The out-of-box basic model does not set this claim but it can be set with the user attribute mapping feature, for example the uid attribute can be mapped to relativeNamespace. This feature is controlled through cluster configuration so is distinct from policy settings. Since the user->relativeNamespace value is always "scrubbed" the resulting namespace will always be valid namespace syntax. See cluster configuration documentation on ldap_basic for details.