AuthService: gRPC API Contract

Version	Date	Author	Change Description
1.0	2025-09-04	Senior Systems Analyst	Initial contract for local password authentication.
2.0	2025-09-11	Senior Systems Analyst	Complete rewrite for Google SSO. Replaced AuthenticateUser with HandleGoogleAuthCallback, removed password fields.

1.0 Overview

This document defines the formal gRPC service contract for the AuthService. All backend services, including the API Gateway, must communicate with the AuthService using the RPCs and message structures defined here. This contract is designed using Protocol Buffers v3 (proto3) syntax.

2.0 Service Definition: AuthService

// The primary service for handling authentication, authorization, and user management.  
service AuthService {  
  // Handles the callback from the Google SSO flow.  
  // Exchanges the authorization code for user info, performs JIT provisioning,  
  // and creates an application session.  
  rpc HandleGoogleAuthCallback(HandleGoogleAuthCallbackRequest) returns (HandleGoogleAuthCallbackResponse);

  // Validates a session token and returns the associated user ID.  
  // Used by the API Gateway to authenticate every incoming request.  
  rpc ValidateSession(ValidateSessionRequest) returns (ValidateSessionResponse);

  // Checks if a user has a specific permission.  
  // Used by the API Gateway for authorization checks.  
  rpc CheckPermission(CheckPermissionRequest) returns (CheckPermissionResponse);

  // Invites a new user, creating a pre-provisioned record with an 'Invited' status.  
  rpc InviteUser(InviteUserRequest) returns (InviteUserResponse);

  // --- Standard CRUD Operations ---

  // Retrieves a user's details by their ID.  
  rpc GetUser(GetUserRequest) returns (User);

  // Updates a user's details (e.g., status, roles, groups).  
  rpc UpdateUser(UpdateUserRequest) returns (User);

  // Lists all users with filtering and pagination.  
  rpc ListUsers(ListUsersRequest) returns (ListUsersResponse);

  // Retrieves a user's full set of effective permissions.  
  rpc GetUserEffectivePermissions(GetUserEffectivePermissionsRequest) returns (GetUserEffectivePermissionsResponse);  
}

3.0 Message Definitions

3.1 Core Data Structures

// Represents a User account in the system.  
message User {  
  string user_id = 1;         // UUID  
  string google_subject_id = 2; // The unique, immutable ID from Google.  
  string email = 3;  
  string display_name = 4;  
  UserStatus status = 5;  
  google.protobuf.Timestamp created_at = 6;  
  google.protobuf.Timestamp updated_at = 7;  
  google.protobuf.Timestamp last_login_at = 8;  
  repeated Role roles = 9;       // Roles assigned directly to the user.  
  repeated Group groups = 10;    // Groups the user is a member of.  
}

enum UserStatus {  
  UNKNOWN_STATUS = 0;  
  ACTIVE = 1;  
  INACTIVE = 2;  
  INVITED = 3;  
}

// Represents a Role, which is a collection of permissions.  
message Role {  
  string role_id = 1; // UUID  
  string name = 2;  
  string description = 3;  
}

// Represents a Group, which users can be members of.  
message Group {  
  string group_id = 1; // UUID  
  string name = 2;  
  string description = 3;  
}

3.2 Authentication & Session RPCs

// Request to handle the Google SSO callback.  
message HandleGoogleAuthCallbackRequest {  
  string authorization_code = 1; // The single-use code from Google's redirect.  
}

// Response after a successful SSO callback.  
message HandleGoogleAuthCallbackResponse {  
  string session_token = 1;     // The new application session token.  
  User user = 2;                // The full user object.  
  bool is_new_user = 3;         // True if the user was just provisioned (JIT).  
}

// Request to validate a session token.  
message ValidateSessionRequest {  
  string session_token = 1;  
}

// Response from a session validation.  
message ValidateSessionResponse {  
  bool is_valid = 1;  
  string user_id = 2; // The user ID associated with the token.  
}

3.3 Authorization RPCs

// Request to check if a user has a permission.  
message CheckPermissionRequest {  
  string user_id = 1;  
  string permission_name = 2; // e.g., "admin:user:edit"  
}

// Response from a permission check.  
message CheckPermissionResponse {  
  bool granted = 1;  
}

3.4 User Management RPCs

// Request to invite a new user.  
message InviteUserRequest {  
  string email = 1;  
  repeated string role_ids = 2;   // List of role IDs to pre-assign.  
  repeated string group_ids = 3;  // List of group IDs to pre-assign.  
}

// Response after inviting a user.  
message InviteUserResponse {  
  User user = 1; // The newly created user with 'Invited' status.  
}

// Request to get a single user.  
message GetUserRequest {  
  string user_id = 1;  
}

// Request to update a user's mutable fields.  
message UpdateUserRequest {  
  string user_id = 1;  
  string display_name = 2;  
  UserStatus status = 3;  
  repeated string role_ids = 4;   // The complete new set of role IDs for the user.  
  repeated string group_ids = 5;  // The complete new set of group IDs for the user.  
}

// Request to list users with filters.  
message ListUsersRequest {  
  int32 page_size = 1;  
  int32 page_token = 2;  
  string filter_by_email = 3;  
  string filter_by_name = 4;  
  UserStatus filter_by_status = 5;  
}

// Response containing a list of users.  
message ListUsersResponse {  
  repeated User users = 1;  
  int32 next_page_token = 2;  
}

// Request to get a user's effective permissions.  
message GetUserEffectivePermissionsRequest {  
  string user_id = 1;  
}

// Response with the list of effective permissions and their sources.  
message GetUserEffectivePermissionsResponse {  
  message EffectivePermission {  
    string permission_name = 1;  
    string source_description = 2; // e.g., "Inherited from Group: Marketing -> Role: Editor"  
  }  
  repeated EffectivePermission permissions = 1;  
}