Principal Service: Add support for multiple user accounts

mojo/services/vanadium/security/interfaces/principal.mojom

-// Copyright 2015 The Chromium Authors. All rights reserved.
-// Use of this source code is governed by a BSD-style license that can be
-// found in the LICENSE file.
+// Copyright 2015 The Chromium Authors. All rights reserved.  Use of this
+// source code is governed by a BSD-style license that can be found in the
+// LICENSE file.
 
 module vanadium;
 
-// Represents the name of an application. |url| is the url of the
-// application. |qualifier| is a string that allows to tie a specific
-// instance of an application to another.
+// Represents the name of an application. |url| is the url of the application.
+// |qualifier| is a string that allows to tie a specific instance of an
+// application to another.
 struct AppInstanceName {
   string url;
   string? qualifier;
 };
 
-// Certificate represents a human-readable name and public-key (DER encoded) pair.
-// The private-key for a certificate is only available for signing operations
-// within the principal service application.
-struct Certificate {
-   string extension;
-   array<uint8>? publickey;
+// Represents a user identity. |email| is the email address of the user, which may
+// be obtained through a third-party authentication flow (e.g., oauth2).
+struct User {
+  string email;

[ashankar, 2015/10/30 02:24:13]

Must it be "email" - would saying "username" be more appropriate?

[ataly, 2015/11/04 00:24:29]

I have been going back and forth on this. The username is not necessarily the
email address. For instance, based on what I understood from Usha, on Android
the username can also be the phone number.

Therefore for now I though we should just promise the email address in the User
object as that is what our Vanadium IDP blessings promise. The other minor
reason is that an email address stands on its own where a username string may
require the identity provider name as well.

[ashankar, 2015/11/04 00:37:10]

On the other hand, we don't want to end up in a position where an email is
required, right?
Anyway, this is fine for now but as this evolves I do think that we might want
to make this username - and email can be one form of username

[ataly, 2015/11/04 21:22:51]

Acknowledged.

+  Blessing user_blessing;

[ashankar, 2015/10/30 02:24:13]

Just "blessing" - it's part of the "User" struct, so don't need the "_user"
suffix?

[ataly, 2015/11/04 00:24:29]

Done.

+  // TODO(ataly, ukode): Include the name of the identity provider?
+  // TODO(ataly, ukode): Include the first and last name of the user?
+  // TODO(ataly, ukode): Include any unique ids assigned to the user by the
+  // identity provider?
 };
 
-// Blessing is a credential binding a user identity to a public key. The corresponding
-// private key is only available for signing within the PrincipalService application.
-struct Blessing {
-   array<Certificate> chain;
+// Certificate represents a human-readable name and public-key (DER encoded)
+// pair.  The private-key for a certificate is only available for signing
+// operations within the principal service application.
+struct Certificate {
+  string extension;
+  array<uint8>? publickey;
 };
 
-// ChainSeparator is the separator used to join name extensions in a certificate chain.
+// Blessing is a credential binding a user identity to a public key. The
+// corresponding private key is only available for signing within the
+// PrincipalService application.
+// TODO(ataly, gauthamt): This Blessing type does not match the Vanadium
+// WireBlessing type. For the blessing to be usable by SyncBase we will have
+// to make it match the WireBlessing type.

[ashankar, 2015/10/30 02:24:13]

Would it make sense to link to the security concepts page:
https://github.com/vanadium/docs/blob/master/concepts/security.md
as a form of documentation?

[ataly, 2015/11/04 00:24:29]

Done.

+struct Blessing {
+  array<Certificate> chain;
+};
+
+// ChainSeparator is the separator used to join name extensions in a
+// certificate chain.
 const string ChainSeparator = "/";
 
-// A service that binds user identities to an application instance running in Mojo
+// A service that binds user identities to an application instance running in
+// Mojo. An application instance may have multiple user identities with one of
+// them set as the current identity.
 interface PrincipalService {
   // Login is called by an application instance (requestor_url/qualifier) that
-  // wants to get a user blessing. The service may obtain the user blessing
-  // through a third-party authentication flow (eg:oauth2). The user blessing
-  // is bound to a public/private key-pair that this service generates and
-  // persists for this application instance. Returns null if login fails.
-  Login() => (Blessing? user_blessing);
+  // wants to get a new user identity. The service may obtain the user identity
+  // through a third-party authentication flow (e.g., oauth2) which may involve
+  // user intervention. The obtained identity is added to the set of
+  // authenticated user identities of the application instance, and is also set
+  // as the current user identity for the instance.

[gautham, 2015/10/28 23:02:45]

application instance. 

[ataly, 2015/11/04 00:24:29]

Done.

+  //
+  // Additionally, the service creates a user blessing that binds the obtained
+  // email address of the user to the unique public/private key-pair of the instance.

[gautham, 2015/10/28 23:02:45]

application instance. 

[ataly, 2015/11/04 00:24:29]

Done.

+  // This key pair is generated and persisted by this service on the first Login

[gautham, 2015/10/28 23:02:45]

This seems like an implementation detail. Not sure its needed in API level
comments.

[ataly, 2015/11/04 00:24:29]

Done.

+  // invocation by the application instance.
+  //
+  // Returns the user identifier or null if an error is encountered at any
+  // stage.
+  Login() => (User? user);
 
-  // Removes the user blessing for the application instance that invokes the
-  // Logout method.
+  // GetUsers returns all authenticated user identities and the current user
+  // identity of the calling application instance. The user identities are a
+  // result of previous Login calls by the instance.
+  //
+  // The current user identity may be null if the instance is in logged out
+  // state (see 'Logout').
+  GetUsers() => (array<User> ids, User? current);

[gautham, 2015/10/28 23:02:45]

maybe call this GetAuthenticatedUsers or GetLoggedInUsers

Also, given that we have a GetUser() below do we need to return current here as
part of this interface?

[ashankar, 2015/10/30 02:24:13]

+1.
Also, is mojo style to have the "Get" prefix or do they generally do away with
it?
Basically, let's just stick with their convention (and maybe you are, I'm jus'
sayin' :)

[ataly, 2015/11/04 00:24:29]

Done.

+
+  // SetCurrentUser sets the provided identity as the current user identity of

[gautham, 2015/10/28 23:02:45]

SetCurrentUser sets the current user identity of the calling application
instance....

[ataly, 2015/11/04 00:24:29]

Done.

+  // the calling application instance. The provided identity must be present in
+  // the set of authenticated user identities for the application instance,
+  // otherwise an error is returned.
+  SetCurrentUser(User user) => (string? error);
+
+  // Logout sets the current user identity of the calling application instance
+  // to null.
   Logout();

[ashankar, 2015/10/30 02:24:13]

Nit: Would re-order things so that related methods are together:

Login();
Logout()
GetLoggedInUsers()

SetCurrentUser()
GetCurrentUser()

[ataly, 2015/11/04 00:24:29]

Done.

 
-  // GetUserBlessing returns the user blessing for a given application instance.
-  // It returns an error if the application instance has not invoked Login().
-  GetUserBlessing(AppInstanceName app) => (Blessing? user_blessing);
+  // GetUser returns the current user identity for a given application instance.
+  // If a null application instance is provided then the current user identifier

[gautham, 2015/10/28 23:02:45]

identifier -> identity

[ataly, 2015/11/04 00:24:29]

Done.

+  // of the calling application instance is returned.
+  //
+  // Returns null if the application instance has not invoked Login.

[gautham, 2015/10/28 23:02:45]

Returns null if the application instance is in logged out state (see 'Logout').

[ataly, 2015/11/04 00:24:30]

Done.

+  GetUser(AppInstanceName? app) => (User? user);

[gautham, 2015/10/28 23:02:45]

GetUser -> GetCurrentUser given that we have SetCurrentUser.

[ataly, 2015/11/04 00:24:29]

Since we renamed GetUsers to GetLoggedInUsers, I renamed SetCurrentUser to
SetUser.

 };
-