dex/api/v2/api.proto

syntax = "proto3";

package api;

option java_package = "com.coreos.dex.api";
option go_package = "github.com/dexidp/dex/api/v2;api";

// Client represents an OAuth2 client.
message Client {
  string id = 1;
  string secret = 2;
  repeated string redirect_uris = 3;
  repeated string trusted_peers = 4;
  bool public = 5;
  string name = 6;
  string logo_url = 7;
  repeated string allowed_connectors = 8;
}

// ClientInfo represents an OAuth2 client without sensitive information.
message ClientInfo {
  string id = 1;
  repeated string redirect_uris = 2;
  repeated string trusted_peers = 3;
  bool public = 4;
  string name = 5;
  string logo_url = 6;
  repeated string allowed_connectors = 7;
}

// GetClientReq is a request to retrieve client details.
message GetClientReq {
  // The ID of the client.
  string id = 1;
}

// GetClientResp returns the client details.
message GetClientResp {
  Client client = 1;
}

// CreateClientReq is a request to make a client.
message CreateClientReq {
  Client client = 1;
}

// CreateClientResp returns the response from creating a client.
message CreateClientResp {
  bool already_exists = 1;
  Client client = 2;
}

// DeleteClientReq is a request to delete a client.
message DeleteClientReq {
  // The ID of the client.
  string id = 1;
}

// DeleteClientResp determines if the client is deleted successfully.
message DeleteClientResp {
  bool not_found = 1;
}

// UpdateClientReq is a request to update an existing client.
message UpdateClientReq {
    string id = 1;
    repeated string redirect_uris = 2;
    repeated string trusted_peers = 3;
    string name = 4;
    string logo_url = 5;
    repeated string allowed_connectors = 6;
}

// UpdateClientResp returns the response from updating a client.
message UpdateClientResp {
    bool not_found = 1;
}

// ListClientReq is a request to enumerate clients.
message ListClientReq {}

// ListClientResp returns a list of clients.
message ListClientResp {
  repeated ClientInfo clients = 1;
}

// TODO(ericchiang): expand this.

// Password is an email for password mapping managed by the storage.
message Password {
  string email = 1;

  // Currently we do not accept plain text passwords. Could be an option in the future.
  bytes hash = 2;
  string username = 3;
  string user_id = 4;
}

// CreatePasswordReq is a request to make a password.
message CreatePasswordReq {
  Password password = 1;
}

// CreatePasswordResp returns the response from creating a password.
message CreatePasswordResp {
  bool already_exists = 1;
}

// UpdatePasswordReq is a request to modify an existing password.
message UpdatePasswordReq {
  // The email used to lookup the password. This field cannot be modified
  string email = 1;
  bytes new_hash = 2;
  string new_username = 3;
}

// UpdatePasswordResp returns the response from modifying an existing password.
message UpdatePasswordResp {
  bool not_found = 1;
}

// DeletePasswordReq is a request to delete a password.
message DeletePasswordReq {
  string email = 1;
}

// DeletePasswordResp returns the response from deleting a password.
message DeletePasswordResp {
  bool not_found = 1;
}

// ListPasswordReq is a request to enumerate passwords.
message ListPasswordReq {}

// ListPasswordResp returns a list of passwords.
message ListPasswordResp {
  repeated Password passwords = 1;
}

// Connector is a strategy used by Dex for authenticating a user against another identity provider
message Connector {
  string id = 1;
  string type = 2;
  string name = 3;
  bytes config = 4;
  repeated string grant_types = 5;
}

// CreateConnectorReq is a request to make a connector.
message CreateConnectorReq {
  Connector connector = 1;
}

// CreateConnectorResp returns the response from creating a connector.
message CreateConnectorResp {
  bool already_exists = 1;
}

// GrantTypes wraps a list of grant types to distinguish between
// "not specified" (no update) and "empty list" (unrestricted).
message GrantTypes {
  repeated string grant_types = 1;
}

// UpdateConnectorReq is a request to modify an existing connector.
message UpdateConnectorReq {
  // The id used to lookup the connector. This field cannot be modified
  string id = 1;
  string new_type = 2;
  string new_name = 3;
  bytes new_config = 4;
  // If set, updates the connector's allowed grant types.
  // An empty grant_types list means unrestricted (all grant types allowed).
  // If not set (null), grant types are not modified.
  GrantTypes new_grant_types = 5;
}

// UpdateConnectorResp returns the response from modifying an existing connector.
message UpdateConnectorResp {
  bool not_found = 1;
}

// DeleteConnectorReq is a request to delete a connector.
message DeleteConnectorReq {
  string id = 1;
}

// DeleteConnectorResp returns the response from deleting a connector.
message DeleteConnectorResp {
  bool not_found = 1;
}

// ListConnectorReq is a request to enumerate connectors.
message ListConnectorReq {}

// ListConnectorResp returns a list of connectors.
message ListConnectorResp {
  repeated Connector connectors = 1;
}

// VersionReq is a request to fetch version info.
message VersionReq {}

// VersionResp holds the version info of components.
message VersionResp {
  // Semantic version of the server.
  string server = 1;
  // Numeric version of the API. It increases every time a new call is added to the API.
  // Clients should use this info to determine if the server supports specific features.
  int32 api = 2;
}

// DiscoveryReq is a request to fetch discover information.
message DiscoveryReq {}

//DiscoverResp holds the version oidc disovery info.
message DiscoveryResp {
  string issuer = 1;
  string authorization_endpoint = 2;
  string token_endpoint = 3;
  string jwks_uri = 4;
  string userinfo_endpoint = 5;
  string device_authorization_endpoint = 6;
  string introspection_endpoint = 7;
  repeated string grant_types_supported = 8;
  repeated string response_types_supported = 9;
  repeated string subject_types_supported = 10;
  repeated string id_token_signing_alg_values_supported = 11;
  repeated string code_challenge_methods_supported = 12;
  repeated string scopes_supported = 13;
  repeated string token_endpoint_auth_methods_supported = 14;
  repeated string claims_supported = 15;
}

// RefreshTokenRef contains the metadata for a refresh token that is managed by the storage.
message RefreshTokenRef {
  // ID of the refresh token.
  string id = 1;
  string client_id = 2;
  int64 created_at = 5;
  int64 last_used = 6;
}

// ListRefreshReq is a request to enumerate the refresh tokens of a user.
message ListRefreshReq {
  // The "sub" claim returned in the ID Token.
  string user_id = 1;
}

// ListRefreshResp returns a list of refresh tokens for a user.
message ListRefreshResp {
  repeated RefreshTokenRef refresh_tokens = 1;
}

// RevokeRefreshReq is a request to revoke the refresh token of the user-client pair.
message RevokeRefreshReq {
  // The "sub" claim returned in the ID Token.
  string user_id = 1;
  string client_id = 2;
}

// RevokeRefreshResp determines if the refresh token is revoked successfully.
message RevokeRefreshResp {
  // Set to true is refresh token was not found and token could not be revoked.
  bool not_found = 1;
}

message VerifyPasswordReq {
  string email = 1;
  string password = 2;
}

message VerifyPasswordResp {
  bool verified = 1;
  bool not_found = 2;
}

// Dex represents the dex gRPC service.
service Dex {
  // GetClient gets a client.
  rpc GetClient(GetClientReq) returns (GetClientResp) {};
  // CreateClient creates a client.
  rpc CreateClient(CreateClientReq) returns (CreateClientResp) {};
  // UpdateClient updates an existing client
  rpc UpdateClient(UpdateClientReq) returns (UpdateClientResp) {};
  // DeleteClient deletes the provided client.
  rpc DeleteClient(DeleteClientReq) returns (DeleteClientResp) {};
  // ListClients lists all client entries.
  rpc ListClients(ListClientReq) returns (ListClientResp) {};
  // CreatePassword creates a password.
  rpc CreatePassword(CreatePasswordReq) returns (CreatePasswordResp) {};
  // UpdatePassword modifies existing password.
  rpc UpdatePassword(UpdatePasswordReq) returns (UpdatePasswordResp) {};
  // DeletePassword deletes the password.
  rpc DeletePassword(DeletePasswordReq) returns (DeletePasswordResp) {};
  // ListPassword lists all password entries.
  rpc ListPasswords(ListPasswordReq) returns (ListPasswordResp) {};
  // CreateConnector creates a connector.
  rpc CreateConnector(CreateConnectorReq) returns (CreateConnectorResp) {};
  // UpdateConnector modifies existing connector.
  rpc UpdateConnector(UpdateConnectorReq) returns (UpdateConnectorResp) {};
  // DeleteConnector deletes the connector.
  rpc DeleteConnector(DeleteConnectorReq) returns (DeleteConnectorResp) {};
  // ListConnectors lists all connector entries.
  rpc ListConnectors(ListConnectorReq) returns (ListConnectorResp) {};
  // GetVersion returns version information of the server.
  rpc GetVersion(VersionReq) returns (VersionResp) {};
  // GetDiscovery returns discovery information of the server.
  rpc GetDiscovery(DiscoveryReq) returns (DiscoveryResp) {};
  // ListRefresh lists all the refresh token entries for a particular user.
  rpc ListRefresh(ListRefreshReq) returns (ListRefreshResp) {};
  // RevokeRefresh revokes the refresh token for the provided user-client pair.
  //
  // Note that each user-client pair can have only one refresh token at a time.
  rpc RevokeRefresh(RevokeRefreshReq) returns (RevokeRefreshResp) {};
  // VerifyPassword returns whether a password matches a hash for a specific email or not.
  rpc VerifyPassword(VerifyPasswordReq) returns (VerifyPasswordResp) {};
}