Latest revision as of 16:12, 27 February 2019

Overview

This document summarises the use of additional user attributes, available in Swivel since version 3.9.1.

User attributes have been used since version 3.4 to define destinations for transports. However, this facility has now been extended to allow the use of alternative attributes for authentication (from version 3.9.1) and searching (since 3.9.2). For each attribute field, Swivel will import one entry, if multiple entries are used, only the first is imported. To import multiple attributes, multiple Swivel attributes can be created.

Prerequisites

Swivel 3.10.4 for initial, synchronised or local attributes

Swivel 3.9.2 or higher for attribute search

Swivel 3.9.1 or higher

User Attribute uses

User Attributes can be used for the following purposes:

• Transport destinations (e.g. email address, phone number)
• Alternative usernames for authentication (e.g. Active Directory userPrincipalName)
• User searching (e.g. by surname)
• User identification (e.g. surname, given name)
• Including in messages

User Attributes Synchronisation

By default the Attributes are taken from the users repository. From Swivel version 3.10.4 onwards, this can be changed so that the value may be imported initially or from a local value:

Synchronised: Read its value from the repository and update

Initialised: Only read the value from the repository when the account is created

Local: Never read the value from the repository (e.g. it will be set via an API call)

Importing Additional Attributes From Repositories

Important: if you make any changes to the attribute definitions, you must perform a User Sync before these attributes are available.

In order to make use of additional attributes, you need to define these attributes, and specify how they are imported from your repositories from the Repository -> Attributes menu. (For version 3.9.1 it is located under Transport -> Attributes menu).

Create a new attribute by entering a unique name for it in the Name field of the blank entry at the bottom of the page, and then for each Repository, enter the name of the attribute from that repository that should be imported.

Check the schema for your repository to determine what the correct attributes are. Most LDAP schemas provide at least the following attributes:

• mail - email address
• mobile - mobile telephone number
• sn - surname
• givenName - given (first, or christian) name

Additionally, to provide alternative usernames for authentication, Active Directory provides userPrincipalName and sAMAccountName. Most other LDAP implementations provide uid and cn. Note that it is not necessary to include the main username attribute as a user attribute, but there is no problem in doing so.

XML Repository Attributes

When using the built-in XML repository (or multiple repositories), the list of attribute names that you can use is given below:

Viewing User Attributes

To view current user attributes, simply select the drop-down next to View: and select Attributes.

Authenticating Using Alternative Attributes

Authentication is configured per-Agent, or RADIUS NAS. New fields have been added to enable this feature, as follows:

• Allow alternative usernames - set to Yes to enable alternative usernames.
• Alternative username attributes - a list of permissible username attributes (see below).

Additionally, if you are using the Check Password with repository feature, the following enhancement is available:

• Username attribute for repository - specify the attribute to use as the repository username (see below).

When checking Swivel authentication, you can specify a number of attributes that can be used to identify the user to authenticate. List the names of the attributes as entered in the Name field of the Repository -> Attributes list, NOT the repository attribute name (if they are different). You can separate the individual names with commas, semi-colons or pipe (vertical bar) characters. DO NOT leave spaces before or after the separator, and DO NOT add a trailing separator. You do not have to include the primary username attribute in this list: Swivel will always check that anyway.

When you specify alternative attributes, Swivel will search for the entered username value first against the primary username. If there is no match for this, it will check against all permitted attributes. If this results in multiple matches, it will return the first match, but log a warning. So long as the matches all refer to the same user, this is not a problem, but you should take care when specifying alternative attributes for authentication that the values are unique over the entire database. So, for example, it is OK to have userPrincipalName and mail as authentication attributes, as typically they are unique, and if both attributes return the same value for a particular user, that doesn't matter, as the correct user is identified. However, it is not a good idea to use surname as an authentication attribute, as this is unlikely to be unique.

NOTE: currently it is not possible to create composite user attributes, as you can by adding a prefix or suffix to the primary username.

When checking the repository password, you can specify which attribute to send to the repository with the password. For example, suppose you normally enter sAMAccountName as the primary username, but when checking against Active Directory, you need to provide userPrincipalName. You can now manage this by specifying userPrincipalName as the Username attribute for repository. Then no matter what username is entered to authenticate to Swivel, the identified user's userPrincipalName attribute will be sent to Active Directory for authentication.

Session Requests

Session requests are Single Channel image requests such as the TURing or Dual Channel SMS requests for On Demand Authentication. Attributes can be defined for these on the Swivel Administration Console under:

Server/Single Channel

Server/Dual Channel

set the following:

Allow alternative usernames: Options: Yes/No, default No, set to Yes to allow alternative attributes.

Alternative username attributes: Enter an attribute name to use for sessions requests

Searching Using Alternative Attributes

To enable searching by attributes, the Username search on User Administration has been extended.

NOTE: If you are viewing an editable repository (e.g. an XML repository), make sure that the Database user set is selected in order to enable this feature.

Instead of a fixed Username search, there is now a drop-down containing all the user attributes. If you have included the username as an alternative attribute, this will appear twice, as Username is always the first entry. Simply select the attribute you want to search by, then enter the attribute value, or part-value, to search for.

Transport Destinations

This aspect of user attributes has been available since version 3.4. It refers to the ability to import transport destinations from the repository. By "Transport Destination", we mean typically email address or telephone number, depending on the nature of the transport.

To make a Transport active, you need to do 2 things:

• Select a group which uses that transport, either for security strings or alerts (or both).
• Select a user attribute to use as the destination.

In most cases, the transport attribute is pre-selected: for the SMTP transport, the "mail" attribute is chosen; for all other transports, "phone" is pre-selected, on the assumption that most transports are SMS gateways. However, if you have multiple phone numbers, or your phone number attribute is not called "mail", then you will need to select the appropriate attribute from the drop-down list for the appropriate transport on the Transport -> General page.

Be aware that you must run a User Sync after making any changes to the transport destination, even if that attribute has already been imported. The destination value for individual users is not automatically updated when the attribute changes.

Using Attributes in Messages

You can insert attribute values in alert messages sent to users, by inserting the placeholder %{attrname}, where attrname is the name of the attribute as defined under Repository -> Attributes. For example, if a user has a custom attribute "given_name" with the value "Tom", and the attribute "family_name" with the value "Smith", then the following message template:

Dear ${given_name} ${family_name}

Will result in the sent message:

Dear Tom Smith

Known Issues and Limitations

Swivel will import the first entry in each attribute only.

Troubleshooting

Ensure that the session request (single and/or dual channel) have multiple attributes enabled as well as the authentication (Agent or RADIUS).