Skip to content

armgit / memos

Public Imported from GitHub
0

Memos is an open-source, self-hosted note-taking app that brings your everyday thoughts together in a personal timeline. Your data stays yours, and you choose what to keep private or share.

7.0 KB
Raw Blame
syntax = "proto3";

package memos.api;

import "google/api/annotations.proto";
import "google/api/client.proto";
import "google/api/field_behavior.proto";
import "google/api/resource.proto";
import "google/protobuf/empty.proto";
import "google/protobuf/field_mask.proto";

option go_package = "gen/api";

// IdentityProviderService manages the external identity providers users can sign in with.
service IdentityProviderService {
  // ListIdentityProviders lists identity providers.
  // Public, so the sign-in page can show SSO options. Client secrets are never returned.
  rpc ListIdentityProviders(ListIdentityProvidersRequest) returns (ListIdentityProvidersResponse) {
    option (google.api.http) = {get: "/api/identity-providers"};
  }

  // GetIdentityProvider gets an identity provider.
  // The client secret is never returned.
  rpc GetIdentityProvider(GetIdentityProviderRequest) returns (IdentityProvider) {
    option (google.api.http) = {get: "/api/{name=identity-providers/*}"};
    option (google.api.method_signature) = "name";
  }

  // CreateIdentityProvider creates an identity provider.
  // Requires the admin role. Fails with FAILED_PRECONDITION when the ID belongs to a provider configured by the
  // deployment.
  rpc CreateIdentityProvider(CreateIdentityProviderRequest) returns (IdentityProvider) {
    option (google.api.http) = {
      post: "/api/identity-providers"
      body: "identity_provider"
    };
    option (google.api.method_signature) = "identity_provider";
  }

  // UpdateIdentityProvider updates an identity provider.
  // Requires the admin role. Providers configured by the deployment cannot be updated.
  rpc UpdateIdentityProvider(UpdateIdentityProviderRequest) returns (IdentityProvider) {
    option (google.api.http) = {
      patch: "/api/{identity_provider.name=identity-providers/*}"
      body: "identity_provider"
    };
    option (google.api.method_signature) = "identity_provider,update_mask";
  }

  // DeleteIdentityProvider deletes an identity provider.
  // Requires the admin role. Providers configured by the deployment cannot be deleted. Fails with
  // FAILED_PRECONDITION when password sign-in is disabled for regular users and no other effective provider remains.
  rpc DeleteIdentityProvider(DeleteIdentityProviderRequest) returns (google.protobuf.Empty) {
    option (google.api.http) = {delete: "/api/{name=identity-providers/*}"};
    option (google.api.method_signature) = "name";
  }
}

// IdentityProvider is an external identity provider users can sign in with.
message IdentityProvider {
  option (google.api.resource) = {
    type: "memos.api/IdentityProvider"
    pattern: "identity-providers/{idp}"
    singular: "identityProvider"
    plural: "identityProviders"
  };

  // Identifier. The resource name of the identity provider.
  // Format: identity-providers/{idp}
  string name = 1 [(google.api.field_behavior) = IDENTIFIER];

  // Required. The type of the identity provider.
  Type type = 2 [(google.api.field_behavior) = REQUIRED];

  // Required. The display title of the identity provider.
  string title = 3 [(google.api.field_behavior) = REQUIRED];

  // Optional. A regular expression the user identifier must match to sign in. Empty allows every identifier.
  string identifier_filter = 4 [(google.api.field_behavior) = OPTIONAL];

  // Required. The type-specific configuration of the identity provider.
  IdentityProviderConfig config = 5 [(google.api.field_behavior) = REQUIRED];

  // Type is the protocol of an identity provider.
  enum Type {
    TYPE_UNSPECIFIED = 0;
    // OAuth2 identity provider.
    OAUTH2 = 1;
  }
}

// Request message for IdentityProviderService.ListIdentityProviders.
message ListIdentityProvidersRequest {}

// Response message for IdentityProviderService.ListIdentityProviders.
message ListIdentityProvidersResponse {
  // The identity providers.
  repeated IdentityProvider identity_providers = 1;
}

// Request message for IdentityProviderService.GetIdentityProvider.
message GetIdentityProviderRequest {
  // Required. The resource name of the identity provider to get.
  // Format: identity-providers/{idp}
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {type: "memos.api/IdentityProvider"}
  ];
}

// Request message for IdentityProviderService.CreateIdentityProvider.
message CreateIdentityProviderRequest {
  // Required. The identity provider to create.
  IdentityProvider identity_provider = 1 [(google.api.field_behavior) = REQUIRED];

  // Optional. The ID to use for the identity provider, which becomes the final component of the resource name.
  // If empty, the server generates one.
  // Format: ^[a-zA-Z0-9]([a-zA-Z0-9-]{0,34}[a-zA-Z0-9])?$
  string identity_provider_id = 2 [(google.api.field_behavior) = OPTIONAL];
}

// Request message for IdentityProviderService.UpdateIdentityProvider.
message UpdateIdentityProviderRequest {
  // Required. The identity provider to update. Its name identifies the provider.
  IdentityProvider identity_provider = 1 [(google.api.field_behavior) = REQUIRED];

  // Required. The fields to update. Supported paths: title, identifier_filter, config; other paths are ignored.
  // An empty OAuth2 client secret in config keeps the stored secret.
  google.protobuf.FieldMask update_mask = 2 [(google.api.field_behavior) = REQUIRED];
}

// Request message for IdentityProviderService.DeleteIdentityProvider.
message DeleteIdentityProviderRequest {
  // Required. The resource name of the identity provider to delete.
  // Format: identity-providers/{idp}
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {type: "memos.api/IdentityProvider"}
  ];
}

// IdentityProviderConfig is the type-specific configuration of an identity provider.
message IdentityProviderConfig {
  // The configuration, matching the provider type.
  oneof config {
    // The configuration of an OAuth2 identity provider.
    OAuth2Config oauth2_config = 1;
  }
}

// OAuth2Config is the configuration of an OAuth2 identity provider.
message OAuth2Config {
  // The OAuth2 client ID.
  string client_id = 1;

  // The OAuth2 client secret. Write-only: it is never returned in responses.
  string client_secret = 2;

  // The authorization endpoint URL.
  string auth_url = 3;

  // The token endpoint URL, used to exchange the authorization code for an access token.
  string token_url = 4;

  // The user info endpoint URL, used to fetch the claims of the signed-in user.
  string user_info_url = 5;

  // The scopes to request.
  repeated string scopes = 6;

  // How user info claims map to user fields.
  FieldMapping field_mapping = 7;
}

// FieldMapping maps user info claims of an OAuth2 identity provider to user fields.
// Each field holds the name of a claim.
message FieldMapping {
  // The claim that uniquely identifies the user. Sign-in fails when it is missing or empty.
  string identifier = 1;

  // The claim used as the display name. Falls back to the identifier when unset.
  string display_name = 2;

  // The claim used as the email address.
  string email = 3;

  // The claim used as the avatar URL.
  string avatar_url = 4;
}