Difference between revisions of "User Attributes How To"
(No difference)
|
Revision as of 17:29, 24 February 2015
Contents
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)
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:
Attribute | Local XML | LDAP | Active Directory | ADAM |
phone | phone | phone | mobile | mobile |
username | username | cn | sAMAccountName | cn |
altusername | custom | uid | userPrincipalName | uid |
familyname | last-name | sn | sn | sn |
givenname | first-name | givenName | givenName | givenName |
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.
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).