github.com/pachyderm/pachyderm@v1.13.4/src/client/auth/auth.proto

syntax = "proto3";

package auth;
option go_package = "github.com/pachyderm/pachyderm/src/client/auth";

import "gogoproto/gogo.proto";
import "google/protobuf/timestamp.proto";

/* A note on users
 *
 * Internally, in Pachyderm, usernames are structured strings. This makes both
 * our API and our data model more flexible (at the loss of some type safety).
 * Basically, anywhere that Pachyderm internally stores a subject (i.e.
 * TokenInfo) or principal (ACL, the 'admins' collection), that username will
 * have some structured prefix.
 *
 * Note that externally-facing principals ({Get,Set}{Scope,ACL}, ModifyAdmins,
 * ListAdmins) will have their own conventions
 *
 * The current user formats are:
 * 1) GitHub usernames:
 *      "github:MyGitHubUsername"
 * 2) Pachyderm robot users:
 *      "robot:robot_user_1"
 * 3) Pachyderm pipelines:
 *      "pipeline:terasort"
 */

//// Activation API

// ActivateRequest mirrors AuthenticateRequest. The caller is authenticated via
// GitHub OAuth, and then promoted to the cluster's first Admin. Afterwards, the
// caller can promote other users to Admin and remove themselves
message ActivateRequest {
  // If set, Pachyderm will authenticate the caller as this user.
  // - If set to a github user (i.e. it has a 'github:' prefix or no prefix)
  //   then Pachyderm will confirm that it matches the user associated with
  //   'github_token'
  // - If set to a robot user (i.e. it has a 'robot:' prefix), then Pachyderm
  //   will generate a new token for the robot user; this token will be the only
  //   way to administer this cluster until more admins are added.
  string subject = 2;

  // This is the token returned by GitHub and used to authenticate the caller.
  // When Pachyderm is deployed locally, setting this value to a given string
  // will automatically authenticate the caller as a GitHub user whose username
  // is that string (unless this "looks like" a GitHub access code, in which
  // case Pachyderm does retrieve the corresponding GitHub username)
  string github_token = 1 [(gogoproto.customname) = "GitHubToken"];

  // If set, activate auth for the root user (`pach:root`), and add this
  // token as the initial login token. The root user will have super
  // admin permissions on the cluster.
  string root_token = 3;
}

message ActivateResponse {
  // pach_token authenticates the caller with Pachyderm (if you want to perform
  // Pachyderm operations after auth has been activated as themselves, you must
  // present this token along with your regular request)
  string pach_token = 1;
}

message DeactivateRequest {}
message DeactivateResponse {}

// IDProvider configures a single ID provider that can authenticate Pachyderm
// users
message IDProvider {
  // Name identifies this authentication backend in Pachyderm.
  string name = 1;

  // Description is a human-readable description of this authentication
  // backend. It's ignored by Pachyderm, but exists for the benefit of users
  // configuring Pachyderm's auth system.
  string description = 2;

  // SAMLOptions describes a SAML-based identity provider
  message SAMLOptions {
    // metadata_url is the URL of the SAML ID provider's metadata service
    // (which Pachd can query to get more info about the SAML ID provider)
    string metadata_url = 1 [(gogoproto.customname) = "MetadataURL"];

    // metadata_xml is a direct reproduction of the ID provider's metadata.
    // Users can set this field in the argument to SetConfig if the ID provider
    // can't be reached from pachd (e.g. because it's on a separate network to
    // which Pachyderm users also have access) or for testing.  Exactly one of
    // metadata_url and metadata_xml should be set in calls to SetConfig, but
    // internally, if metadata_url is set, the result of scraping the metadata
    // URL will be placed here in the result from GetConfig().
    bytes metadata_xml = 2 [(gogoproto.customname) = "MetadataXML"];

    // If this ID provider supports sending group memberships via attribute,
    // then users can set group_attribute to the SAML attribute that indicates
    // group mmbership, and Pachyderm will update users' group memberships when
    // they authenticate.
    string group_attribute = 3;
  }
  SAMLOptions saml = 3 [(gogoproto.customname) = "SAML"];

   // OIDCOptions describes a OIDC-based identity provider
   message OIDCOptions {
     string issuer = 1;
     string client_id = 2 [(gogoproto.customname) = "ClientID"];
     string client_secret = 3;
     string redirect_uri = 4 [(gogoproto.customname) = "RedirectURI"];
     repeated string additional_scopes = 5;
     bool ignore_email_verified = 6;
  }
  OIDCOptions oidc = 5 [(gogoproto.customname) = "OIDC"];

  // GitHubOptions is an empty protobuf message whose presence in the IDProvider
  // of an AuthConfig indicates that GitHub auth should be enabled.
  message GitHubOptions{}
  GitHubOptions github = 4 [(gogoproto.customname) = "GitHub"];
}

// Configure Pachyderm's auth system (particularly authentication backends
message AuthConfig {
  // live_config_version identifies the version of a given pachyderm cluster's
  // current auth configuration; if a user tries to write an auth configuration
  // where live_config_version doesn't match the version of the cluster's
  // current config, the write will fail. This allows for safe
  // read+modify+write config changes.
  int64 live_config_version = 1;

  // id_providers describes external ID providers that can authenticate
  // Pachyderm users (e.g. GitHub, Okta, etc)
  repeated IDProvider id_providers = 2 [(gogoproto.customname) = "IDProviders"];

  // saml_svc_options configures the SAML services (Assertion Consumer Service
  // and Metadata Service) that Pachd can export.
  message SAMLServiceOptions {
    // acs is the URL of Pachd's Assertion Consumer Service (i.e. where SAML ID
    // providers can send SAMLResponses to Pachd). If Pachyderm is running in a
    // private cluster, the cluster admin would be responsible for setting up a
    // domain name/proxy to resolve to pachd:654/acs
    string acs_url = 1 [(gogoproto.customname) = "ACSURL"];

    // metadata_url is the public URL of Pachd's SAML metadata service (some
    // SAML ID providers will query this for information about Pachyderm's SAML
    // implementation and use it to idenfity Pachyderm as a service provider).
    // If Pachyderm is running in a private cluster, the cluster admin would be
    // responsible for creating this URL (which must resolve to
    // pachd:654/saml/metadata)
    string metadata_url = 2 [(gogoproto.customname) = "MetadataURL"];

    // dash_url is the public address of this cluster's Pachyderm
    // dashboard, if one exists; this option determines where users will be
    // redirected after successfully authenticating
    string dash_url = 3 [(gogoproto.customname) = "DashURL"];

    // session_duration determines the duration of SAML-IdP-authenticated user
    // sessions (specified as a Golang time duration, e.g. "24h" or "600m"). If
    // unset, user sessions last 24 hours (a short default, as SAML assertions
    // may contain group memberships that need to be refreshed)
    string session_duration = 4;

    // debug_logging determines whether pachd emits verbose logs (including
    // SAML credentials) as it receives them, which may be helpful for
    // debugging. This will probably not be present in any official releases.
    bool debug_logging = 5;
  }
  SAMLServiceOptions saml_svc_options = 3 [(gogoproto.customname) = "SAMLServiceOptions"];
}

message GetConfigurationRequest {}
message GetConfigurationResponse {
  AuthConfig configuration = 1;
}
message SetConfigurationRequest {
  AuthConfig configuration = 1;
}
message SetConfigurationResponse {}

enum ClusterRole {
    UNDEFINED = 0;

    // SUPER gives access to all APIs and owner on everything in PFS (previous just called admin)
    SUPER = 1;

    // FS gives Owner on all repos in PFS but not access to manage other aspects of the cluster
    FS = 2;
  }

// ClusterRoles reflects any cluster-wide permissions a principal has.
// A principal can have multiple cluster roles.
message ClusterRoles {
  repeated ClusterRole roles = 1;
}

// Get the current set of principals and roles for the cluster
message GetClusterRoleBindingsRequest{}
message GetClusterRoleBindingsResponse{
  // bindings contains a mapping of principals to cluster roles
  map<string, ClusterRoles> bindings = 1;
}

// Set cluster roles for the specified principal. Setting an empty list of roles
// revokes any roles the principal has.
message ModifyClusterRoleBindingRequest {
  string principal = 1;
  ClusterRoles roles = 2;
}
message ModifyClusterRoleBindingResponse {}

// Deprecated. Get the list of cluster super admins.
message GetAdminsRequest{}
message GetAdminsResponse{
  repeated string admins = 1;
}

// Deprecated. Add and remove users from the set of cluster super admins.
message ModifyAdminsRequest {
  repeated string add = 1;
  repeated string remove = 2;
}
message ModifyAdminsResponse {}

//// Authentication data structures

// OTPInfo is the analogue of 'TokenInfo' for Authentication Codes (short-lived,
// one-time-use codes that are passed to the frontend and then exchanged for
// longer-lived tokens)
message OTPInfo {
  // Subject (i.e. Pachyderm account) that a given OTP authenticates. This may
  // be copied into the 'subject' field of a TokenInfo, and therefore has the
  // same format, with the same prefixes.
  string subject = 1;

  // session_expiration indicates when the subject's session expires, a.k.a.
  // when the Token to which this OTP converts expires (likely later than this
  // OTP expires, but never earlier).
  google.protobuf.Timestamp session_expiration = 2;
}

// TokenInfo is the 'value' of an auth token 'key' in the 'tokens' collection
message TokenInfo {
  // Subject (i.e. Pachyderm account) that a given token authorizes. Prefixed
  // with "github:" or "robot:" to distinguish the two classes of
  // Subject in Pachyderm
  string subject = 1;

  enum TokenSource {
    INVALID = 0;
    AUTHENTICATE = 1; // returned by Authenticate()--non-revokeable
    GET_TOKEN = 2;  // returned by GetToken()--revokeable.
  }
  TokenSource source = 2;
}

//// Authentication API

message AuthenticateRequest {
  // Exactly one of 'github_token', 'oidc_state', or 'one_time_password' must be set:

  // This is the token returned by GitHub and used to authenticate the caller.
  // When Pachyderm is deployed locally, setting this value to a given string
  // will automatically authenticate the caller as a GitHub user whose username
  // is that string (unless this "looks like" a GitHub access code, in which
  // case Pachyderm does retrieve the corresponding GitHub username)
  string github_token = 1 [(gogoproto.customname) = "GitHubToken"];
  // This is the session state that Pachyderm creates in order to keep track of
  // information related to the current OIDC session.
  string oidc_state = 3 [(gogoproto.customname) = "OIDCState"];

  // This is a short-lived, one-time-use password generated by Pachyderm, for
  // the purpose of propagating authentication to new clients (e.g. from the
  // dash to pachd)
  string one_time_password = 2;

  // This is an ID Token issued by the OIDC provider.
  string id_token = 4;
}

message AuthenticateResponse {
  // pach_token authenticates the caller with Pachyderm (if you want to perform
  // Pachyderm operations after auth has been activated as themselves, you must
  // present this token along with your regular request)
  string pach_token = 1;
}

message WhoAmIRequest {}

message WhoAmIResponse {
  string username = 1;
  bool is_admin = 2;
  int64 ttl = 3 [(gogoproto.customname) = "TTL"];
  ClusterRoles cluster_roles = 4;
}

//// Authorization data structures

// Scope (actually a "role" in canonical security nomenclature) represents a
// rough level of access that a principal has to a repo
enum Scope {
  // To remove a user's scope from a repo, set their scope to NONE
  NONE = 0;
  READER = 1;
  WRITER = 2;
  OWNER = 3;
}

message ACL {
  // principal -> scope. All principals are the default principal of a Pachyderm
  // subject (i.e. all keys in this map are strings prefixed with either
  // "github:" or "robot:", followed by the name of a GitHub user, all of whom
  // are Pachyderm subjects, or a Pachyderm robot user)
  map<string, Scope> entries = 1;
}

message Users {
  map<string, bool> usernames = 1;
}

message Groups {
  map<string, bool> groups = 1;
}

//// Authorization API

message AuthorizeRequest {
  // repo is the object that the caller wants to access
  string repo = 1;

  // scope is the access level that the caller needs to perform an action
  Scope scope = 2;
}

message AuthorizeResponse {
  // authorized is true if the caller has at least
  // 'AuthorizeRequest.scope'-level access to 'AuthorizeRequest.repo', and false
  // otherwise
  bool authorized = 1;
}

message GetScopeRequest {
  // username is the principal (some of which belong to robots rather than
  // users, but the name is preserved for now to provide compatibility with the
  // pachyderm dash) whose access level is queried. To query the access level
  // of a robot user, the caller must prefix username with "robot:". If
  // 'username' has no prefix (i.e. no ":"), then it's assumed to be a github
  // user's principal.
  string username = 1;

  // repos are the objects to which 'username's access level is being queried
  repeated string repos = 2;
}

message GetScopeResponse {
  // scopes (actually a "role"--see "Scope") are the access level that
  // 'GetScopeRequest.username' has to each repo in 'GetScopeRequest.repos', in
  // the same order that repos appeared in 'repos'.
  repeated Scope scopes = 1;
}

message SetScopeRequest {
  // username is the principal (some of which belong to robots rather than
  // users, but the name is preserved for now to provide compatibility with the
  // pachyderm dash) whose access is being granted/revoked. As with
  // GetScopeRequest, to set the access level of a robot user, the caller must
  // prefix username with "robot:". If 'username' has no prefix (i.e. no ":"),
  // then it's assumed to be a github user's principal.
  string username = 1;

  // repo is the object to which access is being granted/revoked
  string repo = 2;

  // scope (actually a "role"--see "Scope") is the access level that the owner
  // of 'principal' will now have
  Scope scope = 3;
}

message SetScopeResponse {}

message GetACLRequest {
  string repo = 1;
}

message ACLEntry {
  // username is the principal posessing this level of access to this ACL's
  // repo (despite the name, this principal may be for a human github user or a
  // pachyderm robot)
  string username = 1;

  // scope is the level of access that the owner of 'principal' has to this
  // ACL's repo (actually a role in typical security terminology)
  Scope scope = 2;
}

// GetACLReponse contains the list of entries on a Pachyderm ACL.
//
// To avoid migration pain with the Pachyderm dash the list of user principal
// entries and robot principal entries are separate. This way, no prefix or
// other disambiguating device is needed in 'entries' to separate user
// principals from robot principals (which would confuse the dash). Instead,
// the dash can simply ignore robot principals.
message GetACLResponse {
  // entries contains all [user principal] -> [role] mappings. This is separate
  // from robot_entries to avoid migration pain the Pachyderm dashboard
  repeated ACLEntry entries = 1;

  // robot_entries contains all [robot principal] -> [role] mappings. This is
  // separate from entries to be unambiguous (all keys are robot principals, but
  // have no prefixes) while avoiding migration pain in the Pachyderm dashboard.
  repeated ACLEntry robot_entries = 2;
}

message SetACLRequest {
  string repo = 1;
  repeated ACLEntry entries = 2;
}

message SetACLResponse {}

//////////////////////////////
//// OIDC Data Structures ////
//////////////////////////////

// SessionInfo stores information associated with one OIDC authentication
// session (i.e. a single instance of a single user logging in). Sessions are
// short-lived and stored in the 'oidc-authns' collection, keyed by the OIDC
// 'state' token (30-character CSPRNG-generated string). 'GetOIDCLogin'
// generates and inserts entries, then /authorization-code/callback retrieves
// an access token from the ID provider and uses it to retrive the caller's
// email and store it in 'email', and finally Authorize() returns a Pachyderm
// token identified with that email address as a subject in Pachyderm.
message SessionInfo {
  // nonce is used by /authorization-code/callback to validate session
  // continuity with the IdP after a user has arrived there from GetOIDCLogin().
  // This is a 30-character CSPRNG-generated string.
  string nonce = 1;
  // email contains the email adddress associated with a user in their OIDC ID
  // provider. Currently users are identified with their email address rather
  // than their OIDC subject identifier to make switching between OIDC ID
  // providers easier for users, and to make user identities more easily
  // comprehensible in Pachyderm. The OIDC spec doesn't require that users'
  // emails be present or unique, but we think this will be preferable in
  // practice.
  string email = 2;
  // conversion_err indicates whether an error was encountered while exchanging
  // an auth code for an access token, or while obtaining a user's email (in
  // /authorization-code/callback). Storing the error state here allows any
  // sibling calls to Authenticate() (i.e. using the same OIDC state token) to
  // notify their caller that an error has occurred. We avoid passing the caller
  // any details of the error (which are logged by Pachyderm) to avoid giving
  // information to a user who has network access to Pachyderm but not an
  // account in the OIDC provider.
  bool conversion_err = 3;
}

//// OIDC API

message GetOIDCLoginRequest {
}

message GetOIDCLoginResponse {
  // The login URL generated for the OIDC object
  string login_url = 1 [(gogoproto.customname) = "LoginURL"];
  string state = 2;
}

//// Token API (very limited -- for pipelines)

message GetAuthTokenRequest {
  // The returned token will allow the caller to access resources as this
  // subject
  string subject = 1;

  // ttl indicates the requested (approximate) remaining lifetime of this token,
  // in seconds
  int64 ttl = 2 [(gogoproto.customname) = "TTL"];
}

message GetAuthTokenResponse {
  // A canonicalized version of the subject in the request
  string subject = 2;

  // A new auth token for the user in 'GetAuthTokenRequest.Subject' token
  string token = 1;
}

message ExtendAuthTokenRequest {
  // token indicates the Pachyderm token whose TTL is being extended
  string token = 1;

  // ttl indicates the new TTL of 'token' (if it's longer than the existing TTL)
  int64 ttl = 2 [(gogoproto.customname) = "TTL"];
}

message ExtendAuthTokenResponse {}

message RevokeAuthTokenRequest {
  string token = 1;
}

message RevokeAuthTokenResponse {}

message SetGroupsForUserRequest {
  string username = 1;
  repeated string groups = 2;
}

message SetGroupsForUserResponse {}

message ModifyMembersRequest {
  string group = 1;
  repeated string add = 2;
  repeated string remove = 3;
}

message ModifyMembersResponse {}

message GetGroupsRequest {
  string username = 1;
}

message GetGroupsResponse {
  repeated string groups = 1;
}

message GetUsersRequest {
  string group = 1;
}

message GetUsersResponse {
  repeated string usernames = 1;
}

// GetOneTimePassword allows users to generate short-lived (~30s) tokens that
// can be passed to Authenticate() (via AuthenticateRequest.one_time_password)
// and exchanged for a longer-lived pachyderm token. This is more secure than
// GetAuthToken, which produces long-lived authorization tokens.
message GetOneTimePasswordRequest {
  // If the caller is an admin, GetOneTimePassword() can return a code for
  // any user (useful for testing).
  // If the caller is not an admin, GetOneTimePassword() will return an
  // authentication code for the caller if username is unset or set to the
  // caller's username (and will return an error otherwise)
  string subject = 1;

  // ttl indicates the requested (approximate) remaining lifetime of this token,
  // in seconds
  int64 ttl = 2 [(gogoproto.customname) = "TTL"];
}

message GetOneTimePasswordResponse {
  // 'code' is the string that must be presented in
  // AuthenticateRequest.one_time_password to login as
  // GetOneTimePasswordRequest.subject
  string code = 1;

  // expiration is the time at which the token in 'code' will expire
  google.protobuf.Timestamp otp_expiration = 2 [(gogoproto.customname) = "OTPExpiration"];
}

message HashedAuthToken {
  string hashed_token = 1;
  TokenInfo token_info = 2;
  google.protobuf.Timestamp expiration = 3;
}

// ExtractAuthTokens returns all the hashed robot tokens that have been issued.
// User tokens are not extracted as they can be recreated by logging in.
message ExtractAuthTokensRequest {}

message ExtractAuthTokensResponse {
  repeated HashedAuthToken tokens = 1; 
}

// RestoreAuthToken inserts a hashed token that has previously been extracted.
message RestoreAuthTokenRequest {
  HashedAuthToken token = 1; 
}

message RestoreAuthTokenResponse {}

service API {
  // Activate/Deactivate the auth API. 'Activate' sets an initial set of admins
  // for the Pachyderm cluster, and 'Deactivate' removes all ACLs, tokens, and
  // admins from the Pachyderm cluster, making all data publicly accessable
  rpc Activate(ActivateRequest) returns (ActivateResponse) {}
  rpc Deactivate(DeactivateRequest) returns (DeactivateResponse) {}

  rpc GetConfiguration(GetConfigurationRequest) returns (GetConfigurationResponse) {}
  rpc SetConfiguration(SetConfigurationRequest) returns (SetConfigurationResponse) {}

  // Deprecated. GetAdmins returns the current list of cluster super admins
  rpc GetAdmins(GetAdminsRequest) returns (GetAdminsResponse) {}
  // Deprecated. ModifyAdmins adds or removes super admins from the cluster
  rpc ModifyAdmins(ModifyAdminsRequest) returns (ModifyAdminsResponse) {}

  // GetClusterRoleBindings returns the current set of cluster role bindings
  rpc GetClusterRoleBindings(GetClusterRoleBindingsRequest) returns (GetClusterRoleBindingsResponse) {}
  // ModifyAdmin sets the list of admin roles for a principal
  rpc ModifyClusterRoleBinding(ModifyClusterRoleBindingRequest) returns (ModifyClusterRoleBindingResponse) {}

  rpc Authenticate(AuthenticateRequest) returns (AuthenticateResponse) {}
  rpc Authorize(AuthorizeRequest) returns (AuthorizeResponse) {}
  rpc WhoAmI(WhoAmIRequest) returns (WhoAmIResponse) {}

  rpc GetScope(GetScopeRequest) returns (GetScopeResponse) {}
  rpc SetScope(SetScopeRequest) returns (SetScopeResponse) {}
  rpc GetACL(GetACLRequest) returns (GetACLResponse) {}
  rpc SetACL(SetACLRequest) returns (SetACLResponse) {}

  rpc GetOIDCLogin(GetOIDCLoginRequest) returns (GetOIDCLoginResponse) {}

  rpc GetAuthToken(GetAuthTokenRequest) returns (GetAuthTokenResponse) {}
  rpc ExtendAuthToken(ExtendAuthTokenRequest) returns (ExtendAuthTokenResponse) {}
  rpc RevokeAuthToken(RevokeAuthTokenRequest) returns (RevokeAuthTokenResponse) {}

  rpc SetGroupsForUser(SetGroupsForUserRequest) returns (SetGroupsForUserResponse) {}
  rpc ModifyMembers(ModifyMembersRequest) returns (ModifyMembersResponse) {}
  rpc GetGroups(GetGroupsRequest) returns (GetGroupsResponse) {}
  rpc GetUsers(GetUsersRequest) returns (GetUsersResponse) {}

  rpc GetOneTimePassword(GetOneTimePasswordRequest) returns (GetOneTimePasswordResponse) {}
  
  rpc ExtractAuthTokens(ExtractAuthTokensRequest) returns (ExtractAuthTokensResponse) {}
  rpc RestoreAuthToken(RestoreAuthTokenRequest) returns (RestoreAuthTokenResponse) {}
}