View Source

Introduction

There several use cases in Synapse where a user or a team needs to be disambiguated. In the past, a user's email address was the only piece of information that uniquely identified a user in Synapse. However, it is not appropriate to give one user's email address to another user so it is not appropriate to use email addresses for disambiguation. Here are some use cases where disambiguation is needed:

User "Susie Q" sends a project administrator a Synapse message requesting access to private data of the project. When the administrator attempts to grant this user access, they find there are several user's with the name "Susie Q". How do they disambiguated the sender of the message from all of the other users?
A participant in a competition wants to track the top scoring competitor to identify possible alliances. How do they identify the users to contact from the submissions?

Most on-line systems solve these types of problems by providing a "userName", "login", or "alias" that uniquely identified a user in the system. Typically, the web UI will show a user's alias as a link to a user's profile in all contexts where attribution is important.

Adding "principalName"

Users and Teams share the same object space as they both can be added to an ACL. Many security systems refer to an entity that can be authenticated as a Principal, so we are proposing renaming our current UserGroup object to Principal. In addition, we will be adding a new field to Principal called "principalName". Principal names will work similarly to "userNames", "aliases", or "logins" in other on-line systems and will have the following properties:

Principal names are are unique across all users and teams (a team cannot have the same principalName as a user or vice versa).
Principal Name uniqueness is case-insensitive. However, when a principal name is set for a user or a team, the original case will be preservers and displayed (i.e. "JaneSmith" can be used as a principal name, however, it will not be possible to later create a principal name "janesmith" as it would collide with the case-insensitive version of "JaneSmith".
User principal names cannot be changed once they are issued. The only exception to this rule is if the principal name is flag as "requires change" by an administrator.
Team principal names are mutable.
User principal names are limited at alpha-numeric characters (a-z,0-9) and the following characters: '.','-','_'. However, only the alpha-numeric characters contribute to the uniqueness so "jane.smith" and "janesmilth" will be interpreted as the same name.
Team names can contain the same characters as users with the addition of spaces. However, only the alpha-numeric characters contribute to the uniqueness so "Best Team Ever" and "bestteamever" will be interpeted as the same name.

Principal Look-up

We will also be added a new services that can be used to look-up principals (we will be removing the old service GET /userGroupHeaders):

HTTP TYPE	URL	Response	Authentication	JSONP
GET	/principals	Paginated<PrincipalHeader>	False	true

This method will have the following parameters:

Name	Description	Optional
limit	Standard pagination parameter to limit the number of results	false
offset	Standard pagination parameter to control page offest	false
nameFilter	Filter by all principalNames, firstNames, or lastNames, that start with this nameFilter. The "exactNameOnly" parameters determines if this is a prefix or exact match filter.	true
exactNameOnly	Used to limit the name filter to an exact match only. When set to TRUE, only names that match "nameFilter" exactly will be returned. When set to FALSE (or excluded), all names that match the "nameFilter" exactly or with the the "nameFilter" prefix will be returned.	true
principalType	Used to limit results to only teams or users. When included, only principals of the provided type: <USERS, TEAMS> will be returned. When excluded all users and teams will be listed	true
domainType	Used to limit users and teams associated with a given domain. When included only principals associated with the provided domain: <SYNAPSE, BRIDGE> will be returned. When excluded, users or teams from any domain will be listed.	true
nameType	Used to limit prefix look-ups to a type of name. When included, the prefix filter will only be applied to names of the provided type: <PRINCIPAL_NAME, FIRST_NAME, LAST_NAME>. When excluded the prefix will be applied to all name types.	true