AOK Authentication Server¶

AOK is the Helion Stackato authentication management service (replacing Cloud Foundry's UAA Server). It issues tokens via OAuth2 for client applications such as the stackato client and the Management Console. AOK can connect to other back-end SSO services such as LDAP by using different Strategies.

End User Login¶

Web¶

Users log in to the web Management Console as they would with any other web application. The Management Console checks with the AOK endpoint (for example, https://aok.stackato.example.com) in the background.

Client¶

If the strategy has been changed to something other than builtin (see below), then users connecting with the stackato client should be aware that:

The user must enter his or her identifier in the format expected by the strategy used by AOK (for example, a username or an email address).
When using an existing authentication token to log in as a second user (for example, an admin connecting as another user), use the second user's stackato username, not the identifier used by AOK's strategy.

These exceptions also apply when using other Cloud-Foundry-compatible clients.

Strategies¶

The term strategy refers to the method used to authenticate users. There are currently two supported strategies:

builtin: The default builtin strategy uses a local database of users and passwords to authenticate.
ldap: The ldap strategy authenticates using the LDAP server specified in kato config. Any user that can successfully authenticate with the LDAP server will be allowed to use Helion Stackato and will have a (non-admin) user account created for them automatically. The LDAP server must return an email address for the user to allow them to log in to Helion Stackato. AOK will look for the email address under the mail, email, and userPrincipalName attributes.

LDAP groups are not currently supported as a visible construct in Helion Stackato.

The use key in the configuration controls the strategy that AOK will use. This value must correspond exactly to one of the supported strategy names.

Configuration¶

To configure AOK, set the following keys in the AOK config using kato config set:

strategy:
- use: set to either builtin (default) or ldap. The builtin strategy requires no further modification. The ldap strategy requires setting options in the corresponding block below.
- ldap:
  - host: the hostname or IP address of the LDAP server
  - port: the LDAP server port, typically 389
  - method: plain, ssl, or tls
  - base: the list of domain components (for example, dc=example, dc=com)
  - uid: the LDAP attribute name for the username that will used in the login form. Active Directory (AD) is typically sAMAccountName or UserPrincipalName, while OpenLDAP is uid.
  - email: the LDAP attribute containing the user's fully qualified email address. An email address attribute is necessary for AOK to work properly with the cloud controller. This may be a scalar attribute or an array of attributes to search. The default is displayed. The first non-null attribute will be used (AOK will not validate that this is an email address). The default attributes are:
    - mail
    - email
    - userPrincipalName
  - use_email_for_username: (optional) Use the email address as a username in Helion Stackato (Helion Stackato 2.x behavior). Set to true if importing data from Helion Stackato 2.x.
  - bind_dn: (optional) credentials for user lookup (for example, cn=Administrator,cn=Users,dc=example,dc=com). LDAP servers that allow anonymous bind will not require this setting.
  - password: (optional) default credentials for user lookup
  - try_sasl: (optional) when set to true attempts a SASL connection to the LDAP server
  - sasl_mechanims: (optional) DIGEST-MD5 or GSS-SPNEGO
  - group_query: (optional) causes AOK to perform an additional search on the LDAP server after a user has successfully authenticated in order to fetch their group membership (nil or false to disable).
  - group_attribute: (optional) the LDAP attribute to extract from the entries returned by group_query (nil or false to disable).
  - allowed_groups: (optional) comma-separated list of LDAP groups allowed to log in to Helion Stackato.
  - admin_groups: (optional) comma-separated list of LDAP groups which get Helion Stackato admin permissions. Must be an array of Strings.

Note

An additional name_proc option in the ldap block allows users to enter email addresses instead of LDAP usernames, matching the usernames entered with the format of the uid attributes. For example, the value of sAMAccountName in AD contains only the Windows username. If your users prefer using email to login, the following name_proc value trims the email string down to just the Windows login name:

Proc.new {|name| name.gsub(/@.*$/,'')}

The value must be valid Ruby code. Because the provided code will be accepting arbitrary user input, administrators are urged to use this setting only when absolutely necessary, and to check the code thoroughly for possible security implications.

To see the the default AOK configuration (default settings) run the command:

$ kato config get aok

Settings are nested as per the option list above. To set an option, specify the full config path to that option. For example:

$ kato config set aok strategy/ldap/base 'dc=yourdomain, dc=com'

To add an attribute to the email array:

$ kato config push aok strategy/ldap/email "ADMailAcct"

To set the entire array in one step, use the --json option:

$ kato config set --json aok strategy/ldap/email '["mail","ADMailAcct", "email"]'

To make the configuration changes active, run kato restart controller.

LDAP Groups¶

With the LDAP strategy enabled, Helion Stackato can query LDAP groups to:

define which LDAP groups are authorized to use Helion Stackato
define which LDAP groups get Helion Stackato admin privileges

Groups for Authorization¶

Important

When you use LDAP for authentication, usernames that match existing administrator accounts will inherit administrative privileges. Remove administrative privileges from any accounts that overlap with LDAP users who should not have administrative privileges.

To limit which LDAP groups get access to Helion Stackato, the following three options must be set in AOK's strategy/ldap settings:

group_query: The query to run to determine which groups a user belongs to (set in conjunction with group_attribute). For example:
```
$ kato config set aok strategy/ldap/group_query '(&(objectClass=posixGroup)(memberUid=%{username}))'
```
This queries for the posixGroups that the user belongs to:
- %{username} is replaced with the value of the field specified by uid
- %{dn} is replaced by the dn of the authenticated user.
group_attribute: The LDAP attribute to extract from the query above (requires a valid group_query setting). For example:
```
$ kato config set aok strategy/ldap/group_attribute 'cn'
```
This extracts the name of the groups returned by the group_query above if the group's 'cn' (common name) attribute contains its name.
allowed_groups: A list of LDAP groups that are allowed to access Helion Stackato (requires group_attribute and group_query settings). For example:
```
$ kato config set aok strategy/ldap/allowed_groups '["dev", "engineering"]'
```
This would allow only members of the 'dev' or 'engineering' groups to access Helion Stackato.

Admin Groups¶

Helion Stackato can give members of certain LDAP groups admin accounts on Stackato. This requires the following settings:

group_query
group_attribute
admin_groups** A list of LDAP groups that get admin privileges. For example:
```
$ kato config set aok strategy/ldap/admin_groups '["admins", "bosses"]'
```
This gives automatic Helion Stackato admin privileges to members of the admins and bosses LDAP groups.

This can be used with or without allowed_groups limiting regular user-level access to Helion Stackato.

Active Directory Example Settings¶

The following example shows what a typical AOK configuration might look like for an Active Directory server. This configuration:

connects an Active Directory host called ad.example.com
authenticates with the reader account
queries the group object
allows members of the developers and admins groups access to Helion Stackato
gives members of the admins group an admin account in Helion Stackato

use: ldap
ldap:
  host: directory.example.com
  port: 389
  method: plain
  base: DC=directory,DC=example,DC=com
  uid: sAMAccountName
  email:
  - mail
  - email
  - userPrincipalName
  bind_dn: CN=reader,CN=admins,DC=example,DC=com
  password: passwordhere
  group_query: (&(objectCategory=group)(member=%{dn}))
  group_attribute: cn
  allowed_groups:
  - developers
  - admins
  admin_groups:
  - admins

Note

For more information about creating a group_query, see the MSDN documentation on Searching Active Directory and Google documentation on Common LDAP Queries.

User Management¶

When using AOK with any strategy other than builtin, users in Helion Stackato will be created automatically for any user who successfully authenticates.

Administrators can still use the functions as before, but should be aware of the following restrictions:

Administrators may manually create users if they wish. This may be useful if the admin wants to pre-assign users to groups in Helion Stackato before those users have logged in for the first time. The admin must create the user with the same username that AOK will receive from the strategy.
Passwords set while creating users or using the password-change function will be disregarded - Helion Stackato/AOK does not manage the external authentication systems.
Admins may delete users, but the user will be recreated if they log in again via AOK. If an admin wishes to prevent a user from using Helion Stackato, the user's login credentials should be revoked in the external authentication system.

First Administrator Setup¶

When setting up a Helion Stackato system using AOK, complete the Set Up First Admin User page displayed by the web Management Console before configuring LDAP authentication. This creates an administrator, and changes the password of the 'stackato' user on the VM to match whatever was entered in the form.

You may use either a temporary username (for example, firstuser) which will be deleted later, or use the LDAP username you will ultimately use once AOK is configured.

Once the first user has been created:

Log in to the micro cloud VM or core node as the stackato user (with the password set previously)
Configure AOK to use LDAP
Set the admin_user key with the desired LDAP administrator username:
```
$ kato config set aok strategy/ldap/admin_user <username>
```
This user will be granted administrative privileges when logging in for the first time.
If you created a temporary administrative account, delete it at this point.

Default organization and Space¶

When using LDAP authentication, new users logging in to the Management Console will be automatically added to a default organization and space if those defaults have been configured by the admin.

On the organization and Space views in the Management Console, admins will see Set as Default organization or Set as Default Space respectively. To set this using the stackato client:

$ stackato update-org --default [org-name]
$ stackato update-space --default [space-name]

The --default option is also available with the create-org and create-space commands, for use when creating new default organizations and spaces.

Without a default organization and space set, new users logging in via LDAP will be added as users to Helion Stackato, but will not be a member of any organization or space.

Individual organizations for LDAP Users¶

As an alternative to putting new users in one default organization, Helion Stackato can be set to automatically create an new, single-user organization for each new LDAP user that logs in. This simulates the behavior of older Helion Stackato and Cloud Foundry systems where individual users had their own quotas.

The new organizations have the same name as the user (which may be an email address if use_email_for_username is set in AOK).

To enable this behavior, add the following settings to the cloud_controller_ng configuration:

uaa/new_user_strategy: global (default) or individual. When set to individual creates a default org and space when an LDAP user logs in to the management console for the first time. If unset, the default (global) behavior described above is used.
uaa/new_user_strategies/individual: contains the following sub-keys defining how new individual orgs are set up:
- quota_name: name of the quota plan for the org. You should set up a new quota plan specifically for single-user orgs with limits appropriate to the number of users you plan to add to the system.
- space_name: name of the default space created for each new user within their individual org.
- space_role: role of the user in the created space. May be one of manager, auditor, or developer (default).
- organization_role: The role of the user in the created organization: manager, billing_manager, auditor, or user (default).

Use kato config set to set these values, for example:

$ kato config set cloud_controller_ng uaa/new_user_strategy individual

$ kato config set cloud_controller_ng uaa/new_user_strategies/individual/space_name dev

Restart the controller to make the configuration changes active:

$ kato restart controller

Individual Organization Example¶

The following is an example of a typical configuration for creating individual organizations:

$ kato config get cloud_controller_ng uaa

uaa:
  url: https://aok.example.com/uaa
  resource_id: cloud_controller
  symmetric_secret: jezmyCXJ45YWAqr4sG9hvsrlhwMHIK//drcBd76a+L4PMitJTAR4XZKvoUHSuDSL
  new_user_strategy: individual
  new_user_strategies:
    individual:
      space_name: default
      quota_name: single-user
      space_role: manager
      organization_role: manager

This configuration creates a new organization for each LDAP user that logs in, makes the user a manager of their org, creates a space called default, and makes the user a manager for that space.