--- /dev/null
+[[!meta title="Provisioning Identities"]]
+##Provisioning Identities
+
+One of the most significant user experience challenges for moonshot is configuring a machine to use a particular Moonshot identity. In effect, the machine needs to be enabled for moonshot.
+
+There are three ways this can happen:
+
+1. A user wants to use an identity provider website to provision their identity
+2. An administrator wants to provision one or more identities
+3. A user wants to manually add an identity.
+
+The manual case is one that will likely be very uncommon and is not one to focus on.
+
+In addition to provisioning identities, a system administrator may
+wish to provision rules for which services should be used with which
+types of identities.
+
+So, we need to support:
+
+* a identity provider website providing a encoded identity card
+* A system administrator providing an encoded identity card
+* A system administrator providing rules files system wide
+* A system administrator providing rules files for a user
+
+### Encoding considerations
+
+The encoded identity card and encoded rules file need to use some sort of extensible format. We're already depending on JSON using the Jannson library. XML would also be acceptable.
+We can protect these files in transit using TLS and at rest using file permissions. As a result providing cryptographic integrity or confidentiality in the format is not a concern for the first version
+
+### When an identity card is provisioned
+
+* The identity is taken from the encoded identity card and added to the user's database of encoded identities. As a consequence identity cards can only provisioned for a specific user, not for the system.
+* If a password is supplied, this password is saved with the identity card. When provisioning an identity from a website it is typical that a password is provided
+* Rules for service selections are recorded and tied to the identity
+* Any attributes associated with the identity are stored.
+
+No actual services are specifically associated with the identity at
+provisioning time; see the section on identity selection below.
+
+
+Handling updates to an identity is an open question.
+We want to be careful of phishing and to make sure that an updated identity comes from the same source as the existing identity.
+
+### Service selection rules
+
+One of the goals of these enhancements is to minimize or avoid
+entirely situations where the user has to pick an identity. We will
+accomplish this by having rules to describe services. Such a rule may
+match for example all IMAP servers or all servers in a given service
+realm.
+
+These rules can be used in two ways.
+First, they can directly be attached to a provisioned identity. If a service's name matches a rule attached to a given identity, that identity is a candidate for that service.; see the service selection rules below for what happens then.
+
+Secondly, an administrator can attach a service selection rule to an identity selection rule. In this case, the service selection rule may be attached to any identity that matches the identity selection rule.
+
+Service selection rules contain:
+
+* A glob pattern matching a set of services
+* The always_confirm flag; if this flag is set then the user is always prompted to confirm the match
+
+###Selecting a service
+
+####Constructing the service selection rule set
+
+The system maintains a dynamic set of service selection rules that are attached to identities in the system. Given one of these rules the system needs to be able to find the identity to which it is attached. Also, the system needs to be able to find the service selection rules associated with a given identity. Note none of these are comments about what the UI needs to display; simply requirements of the abstract representation.
+
+In particular:
+
+Some service selection rules are stored along side identities. In
+particular, when a service selection rule is part of an encoded
+identity card, it is stored along side that identity. Unless the
+identity is deleted, this rule remains attached to the identity.
+
+However, the user interface also needs to manage the binding between
+service selection rules attached to identity selection rules and
+actual identity cards. To do this, at UI start-up and whenever an
+identity is added, the system enumerates all identity selection
+rules. If an identity selection rule triggers, then the service selection rules associated with the identity selection rule are attached to the identity card that triggered this rule. These rules are only associated in the running instance of the UI; they are not stored with the identity card. If the identity selection rule is removed by an administrator, then any service selection rules from the removed identity selection rule will no longer be present after the next time the UI is reloaded.
+
+####Services associated with identity cards
+
+As in the existing system, an identity card may have an associated set of services. These are not rules: these are single services that the user or system has associated with the identity.
+No automated provisioning will ever populate this list.
+
+
+#### None
+
+The UI needs to maintain a none identity card indicating that Moonshot
+should not be used for a particular service. This card cannot be
+deleted, but it can have services associated with it; these associations may be deleted. No service selection rules can be attached to the none identity.
+
+
+####Algorithm for handling service selection
+
+This algorithm maintains the following state:
+
+* a will_confirm flag initially set to false
+* A set of identity cards called the candidate set, initially empty
+* An identity constraint.
+
+The service selection algorithm is triggered when an application requests a service. The application passes in a NAI, service and password, any of which may be empty.
+
+1. If the NAI is non-empty and an identity card with this NAI exists, then the identity constraint is set to the NAI. The identity card corresponding to this NAI is added to the candidate set.
+
+2. If the system is in a global confirm everything mode per discussions after Prague, set will_confirm to true.
+
+3. For every identity card that has this service associated directly with the identity card (not a triggering rule--the actual service), add the identity card to the candidate set.
+
+4. If the candidate set contains more than one identity card, disassociate this service from all identity cards.
+
+5. If the candidate set is non-empty go to the step labeled "INTERACT".
+
+6. For each service selection rule that triggers on this service, add the identity cards associated with that service selection rule to the candidate set. If any of these rules has the will_confirm flag set to true then set the will_confirm flag in the algorithm state to true.
+
+
+7. INTERACT: If there is more than one identity in the candidate set then set the will_confirm flag to true. If there is an identity constraint, then remove any candidate identity that does not match the identity constraint.
+
+8. If the will_confirm flag is true, then ask the user to select the identity to use. If the candidate set is non-empty then indicate these candidates. They may be indicated by only displaying the candidates with a button to display more options, or by highlighting the candidate set members, or some other appropriate mechanism. The user should also be given the none option.
+
+9. If the service is non-empty then associate the service with the selected identity card.
+
+10. Return the information for the selected identity card to the application.
+
+
+###Attributes of an identity card
+
+* NAI
+* password
+* trust anchor
+* a friendly name like "work account"
+* Service selection rules provisioned with the identity
+* Website for password changing and the like
+
+
+### Attributes of an identity selection rule
+
+* Identity glob pattern
+* set of service selection rules
+
+### Web provisioning of identity
+
+When a website attempts to provision an identity, user interaction is required. The user needs to be given an opportunity to:
+
+* Change or supply the friendly name for the identity
+* Indicate that the UI should always ask before using services with this identity; if so, the will_confirm flag on all service rules for this identity is forced to true
+* Reject the identity as one that should not be provisioned
+
+This work flow is probably not desired when an administrator provisions an identity.
projects / devwiki.git / commitdiff