Add additional rights and clarifications to user management API (#11908)

* user management: document optional primary party

CHANGELOG_BEGIN
CHANGELOG_END

Breaks-protobuf: true

ledger-api/grpc-definitions/com/daml/ledger/api/v1/admin/user_management_service.proto

@@ -39,7 +39,7 @@ service UserManagementService {
     rpc GetUser (GetUserRequest) returns (User);
 
     // Delete an existing user and all its rights.
-    rpc DeleteUser (DeleteUserRequest) returns (google.protobuf.Empty);
+    rpc DeleteUser (DeleteUserRequest) returns (DeleteUserResponse);
 
     // List the all existing users.
     rpc ListUsers (ListUsersRequest) returns (ListUsersResponse);
@@ -72,9 +72,16 @@ message User {
     // The primary party as which this user reads and acts by default on the ledger
     // _provided_ it has the corresponding ``CanReadAs(primary_party)`` or 
     // ``CanActAs(primary_party)`` rights.
+    //
+    // Ledger API clients SHOULD set this field to a non-empty value for all users to
+    // enable the users to act on the ledger using their own Daml party.
+    // Ledger API clients MAY set this field to empty for special users; e.g., a user
+    // that is granted ``CanReadAsAnyParty`` so that it can export the data for all parties
+    // hosted on the participant node.
     string primary_party = 2;
 }
 
+
 // A right granted to a user.
 message Right {
     // The user is allowed to administrate the participant node.
@@ -123,6 +130,9 @@ message DeleteUserRequest {
     string user_id = 1;
 }
 
+message DeleteUserResponse {
+}
+
 // Required authorization: ``HasRight(ParticipantAdmin)``
 message ListUsersRequest {
     // TODO: add pagination, cf. https://cloud.google.com/apis/design/design_patterns#list_pagination