Principal Service: Add support for multiple user accounts

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

Index: mojo/services/vanadium/security/interfaces/principal.mojom
diff --git a/mojo/services/vanadium/security/interfaces/principal.mojom b/mojo/services/vanadium/security/interfaces/principal.mojom
index 9c58834801e7adac99767c3dc0a137cc84896112..c6488363ddf1f44340f5de823ae5a244693968b1 100644
--- a/mojo/services/vanadium/security/interfaces/principal.mojom
+++ b/mojo/services/vanadium/security/interfaces/principal.mojom
@@ -1,49 +1,93 @@
-// 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.
+// Represents a user identifier. |email| is the email address of the user,
+// which may be obtained through a third-party authentication flow (e.g.,
+// oauth2).
+struct UserId {

[ukode, 2015/10/22 20:19:01]

Is UserInfo/UserData or "User" a better option, given this could be extended in
the future?

[ataly, 2015/10/23 21:14:53]

Done, went with 'User'

+  string email;
+  // 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?
+};
+
+// 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;
+  string extension;
+  array<uint8>? publickey;
 };
 
-// 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.
+// 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.
 struct Blessing {
-   array<Certificate> chain;
+  array<Certificate> chain;
 };
 
-// ChainSeparator is the separator used to join name extensions in a 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);
-
-  // Removes the user blessing for the application instance that invokes the
-  // Logout method.
+  // 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.
+  //
+  // Additionally, the service creates a user blessing that binds the obtained
+  // user identity to the unique public/private key-pair of the instance. This
+  // key pair is generated and persisted by this service on the first Login
+  // invocation by the application instance. The constructed blessing may be
+  // obtained by invoking GetUserBlessing().

[ukode, 2015/10/22 20:19:01]

nit: Good to add a TODO here on how/when the blessing becomes invalid during
account change events such as change password or user being disabled or deleted
in the future for abuse reasons.

[ataly, 2015/10/23 21:14:53]

Actually this particular blessing would not invalidate when the user disables
the account, changes passwords etc. The reason is that these blessings do not
carry any caveats. Any caveats obtained on the blessing received from the
Vanadium IDP are stripped out before exposing them to Mojo applications.

Having said that, I plan to change this code soon to make mojo blessings "real",
i.e., usable within Syncbase and Vanadium RPCs in general. I added a TODO on the
blessings type to that effect. We had this simplified definition in the initial
principal service implementaiton mainly because at the time there was no real
use-case for blessings and they were simply used as user identifiers.

[ukode, 2015/10/23 22:45:43]

Acknowledged. Thanks for the clarification.

+  //
+  // Returns the user identifier or null if an error is encountered at any
+  // stage.
+  Login() => (UserId? user_id);

[ukode, 2015/10/22 20:19:01]

On second thought, wondering if we can set the current User identity bit in this
call as well, as the app is requesting for a fresh login anyways. Thoughts? and
setCurrentUser provides the calling app additional support for switching users,
if needed.

Otherwise in normal cases, each app needs to make two auth calls (Login()
followed by setCurrentUser()) which is not really required for a majority of
usecases.

[ataly, 2015/10/23 21:14:53]

Login does set the new identity as the current identity for the app. I mention
this in the last sentence of the first paragraph in the comment. Did you want
Login to take a bool indicating whether the new identity should be made current
or not?

[ukode, 2015/10/23 22:45:43]

This looks good. We don't need a bool again.

+
+  // 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<UserId> ids, UserId? current_id);
+
+  // SetCurrentUser sets the provided identity as the current user identity of
+  // 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(UserId user_id) => (string? error);
+
+  // Logout sets the current user identity of the calling application instance

[ukode, 2015/10/22 20:19:01]

Does logout also delete the entry in Principal Service DB or disabling the cache
entry in the underlying platform?

[ataly, 2015/10/23 21:14:53]

No. Logout does not delete the user entry. It simply clears the "current user
identity" field for the app. A call to GetUsers before and after a Logout call
would only differ in current user identity returned. After Logout the current
user would be null.

[ukode, 2015/10/23 22:45:43]

For now this looks ok, but in the future, we should separate out the account
credential management (add account, update account, delete account) with the
downscoping or signing into app calls as discussed offline.

+  // to null.
   Logout();
 
-  // 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);
+  // GetUserBlessing returns the current user blessing for a given application
+  // instance. If a null application instance is provided then the current user
+  // blessing of the calling application instance is returned.
+  //
+  // Returns null if the application instance has not invoked Login().
+  GetUserBlessing(AppInstanceName? app) => (Blessing? user_blessing);
 };
-