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).
- Team names can contain spaces.
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 |
| prefix | Filter by all principalNames, firstNames, or lastNames, that start with this prefix | 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. | trye |
| 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 |