From 291770fceb1a026b13b8f4cfffdf0ada774f96cd Mon Sep 17 00:00:00 2001 From: Chief-Rishab Date: Wed, 25 Oct 2023 02:10:18 +0530 Subject: [PATCH] chore: update descriptions and examples for docs --- raystack/guardian/v1beta1/guardian.proto | 371 ++++++++++++++++++++--- 1 file changed, 333 insertions(+), 38 deletions(-) diff --git a/raystack/guardian/v1beta1/guardian.proto b/raystack/guardian/v1beta1/guardian.proto index e1b62132..125f61ca 100644 --- a/raystack/guardian/v1beta1/guardian.proto +++ b/raystack/guardian/v1beta1/guardian.proto @@ -29,6 +29,26 @@ option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_swagger) = { { name: "Policies", description: "Policies API" + }, + { + name: "Activities", + description: "Activities API" + }, + { + name: "Appeals", + description: "An appeal is essentially a request created by users to give them access to resources. In order to grant the access, an appeal has to be approved by approvers which is assigned based on the applied policy. Appeal contains information about the requested account, the creator, the selected resources, the specific role for accessing the resource, and options to determine the behaviour of the access e.g. permanent or temporary access." + }, + { + name: "Approvals", + description: "Approvals API" + }, + { + name: "Grants", + description: "Grants API" + }, + { + name: "Namespaces", + description: "Namespaces API" } ] consumes: "application/json"; @@ -90,17 +110,17 @@ option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_swagger) = { } security_definitions: { security: { - key: "Basic"; - value: { - type: TYPE_BASIC; - in: IN_HEADER; - name: "Basic Authentication"; - description: "Client ID/Secret authentication"; - } + key: "apiKey"; + value: { + type: TYPE_API_KEY; + in: IN_HEADER; + description: "Email address of the user"; + name: "X-Auth-Email"; } } +} security: { - security_requirement: {key: "Basic"} + security_requirement: {key: "apiKey"} } }; @@ -111,7 +131,7 @@ service GuardianService { option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = { tags: "Providers"; summary: "List Providers"; - description: "ListProviders returns a list of providers supported by Guardian"; + description: "List Providers returns a list of providers supported by Guardian"; }; } @@ -120,7 +140,7 @@ service GuardianService { option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = { tags: "Providers"; summary: "Get Provider"; - description: "GetProvider returns a provider by ID"; + description: "Get Provider returns a provider by ID"; }; } @@ -129,7 +149,7 @@ service GuardianService { option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = { tags: "Providers"; summary: "Get Provider Types"; - description: "GetProviderTypes returns a list of provider types supported by Guardian"; + description: "Get Provider Types returns a list of provider types supported by Guardian"; }; } @@ -157,7 +177,7 @@ service GuardianService { option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = { tags: "Providers"; summary: "Update Provider"; - description: "UpdateProvider updates a provider config in Guardian"; + description: "Update Provider updates a provider config in Guardian"; }; } @@ -166,16 +186,16 @@ service GuardianService { option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = { tags: "Providers"; summary: "Delete Provider"; - description: "DeleteProvider deletes a provider regsitered in Guardian database"; + description: "Delete Provider deletes a provider regsitered in Guardian database"; }; } rpc ListRoles(ListRolesRequest) returns (ListRolesResponse) { option (google.api.http) = {get: "/v1beta1/providers/{id}/resources/{resource_type}/roles"}; option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = { - tags: "Roles"; + tags: "Providers"; summary: "List Roles"; - description: "ListRoles returns a list of roles supported by a provider. The roles are defined in the provider config."; + description: "List Roles returns a list of roles supported by a provider for a particular resource type."; }; } @@ -184,22 +204,46 @@ service GuardianService { post: "/v1beta1/activities/import" body: "*" }; + option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = { + tags: "Activities"; + summary: "Import Activities"; + }; } rpc GetActivity(GetActivityRequest) returns (GetActivityResponse) { option (google.api.http) = {get: "/v1beta1/activities/{id}"}; + option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = { + tags: "Activities"; + summary: "Get Activity"; + description: "Get Activity returns an activity by ID"; + }; } rpc ListActivities(ListActivitiesRequest) returns (ListActivitiesResponse) { option (google.api.http) = {get: "/v1beta1/activities"}; + option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = { + tags: "Activities"; + summary: "List Activities"; + description: "List Activities returns a list of activities"; + }; } rpc ListPolicies(ListPoliciesRequest) returns (ListPoliciesResponse) { option (google.api.http) = {get: "/v1beta1/policies"}; + option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = { + tags: "Policies"; + summary: "List Policies"; + description: "List Policies returns a list of policies"; + }; } rpc GetPolicy(GetPolicyRequest) returns (GetPolicyResponse) { option (google.api.http) = {get: "/v1beta1/policies/{id}/versions/{version}"}; + option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = { + tags: "Policies"; + summary: "Get Policy"; + description: "Get Policy returns a policy by ID and version"; + }; } rpc CreatePolicy(CreatePolicyRequest) returns (CreatePolicyResponse) { @@ -207,6 +251,11 @@ service GuardianService { post: "/v1beta1/policies" body: "policy" }; + option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = { + tags: "Policies"; + summary: "Create Policy"; + description: "Create Policy creates a new policy in Guardian"; + }; } rpc UpdatePolicy(UpdatePolicyRequest) returns (UpdatePolicyResponse) { @@ -214,18 +263,38 @@ service GuardianService { put: "/v1beta1/policies/{id}" body: "policy" }; + option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = { + tags: "Policies"; + summary: "Update Policy"; + description: "Update Policy updates a policy in Guardian"; + }; } rpc GetPolicyPreferences(GetPolicyPreferencesRequest) returns (GetPolicyPreferencesResponse) { option (google.api.http) = {get: "/v1beta1/policies/{id}/versions/{version}/preferences"}; + option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = { + tags: "Policies"; + summary: "Get Policy Preferences"; + description: "Get Policy Preferences returns a policy preferences by ID and version"; + }; } rpc ListResources(ListResourcesRequest) returns (ListResourcesResponse) { option (google.api.http) = {get: "/v1beta1/resources"}; + option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = { + tags: "Resources"; + summary: "List Resources"; + description: "List Resources returns a list of resources"; + }; } rpc GetResource(GetResourceRequest) returns (GetResourceResponse) { option (google.api.http) = {get: "/v1beta1/resources/{id}"}; + option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = { + tags: "Resources"; + summary: "Get Resource"; + description: "Get Resource returns a resource by ID"; + }; } rpc UpdateResource(UpdateResourceRequest) returns (UpdateResourceResponse) { @@ -233,26 +302,56 @@ service GuardianService { put: "/v1beta1/resources/{id}" body: "resource" }; + option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = { + tags: "Resources"; + summary: "Update Resource"; + description: "Update Resource updates a resource in Guardian"; + }; } rpc DeleteResource(DeleteResourceRequest) returns (DeleteResourceResponse) { option (google.api.http) = {delete: "/v1beta1/resources/{id}"}; + option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = { + tags: "Resources"; + summary: "Delete Resource"; + description: "Delete Resource deletes a resource in Guardian"; + }; } rpc ListUserAppeals(ListUserAppealsRequest) returns (ListUserAppealsResponse) { option (google.api.http) = {get: "/v1beta1/me/appeals"}; + option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = { + tags: "Appeals"; + summary: "List User Appeals"; + description: "List User Appeals returns a list of appeals created by the user"; + }; } rpc ListAppeals(ListAppealsRequest) returns (ListAppealsResponse) { option (google.api.http) = {get: "/v1beta1/appeals"}; + option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = { + tags: "Appeals"; + summary: "List Appeals"; + description: "List Appeals returns a list of appeals"; + }; } rpc GetAppeal(GetAppealRequest) returns (GetAppealResponse) { option (google.api.http) = {get: "/v1beta1/appeals/{id}"}; + option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = { + tags: "Appeals"; + summary: "Get Appeal"; + description: "Get Appeal returns an appeal by ID"; + }; } rpc CancelAppeal(CancelAppealRequest) returns (CancelAppealResponse) { option (google.api.http) = {put: "/v1beta1/appeals/{id}/cancel"}; + option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = { + tags: "Appeals"; + summary: "Cancel Appeal"; + description: "Cancel Appeal cancels an appeal"; + }; } rpc CreateAppeal(CreateAppealRequest) returns (CreateAppealResponse) { @@ -260,14 +359,29 @@ service GuardianService { post: "/v1beta1/appeals" body: "*" }; + option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = { + tags: "Appeals"; + summary: "Create Appeal"; + description: "Create Appeal allows a user to create an access request to resources along with the role"; + }; } rpc ListUserApprovals(ListUserApprovalsRequest) returns (ListUserApprovalsResponse) { option (google.api.http) = {get: "/v1beta1/me/approvals"}; + option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = { + tags: "Approvals"; + summary: "List User Approvals"; + description: "List User Approvals returns a list of approvals created by the current user"; + }; } rpc ListApprovals(ListApprovalsRequest) returns (ListApprovalsResponse) { option (google.api.http) = {get: "/v1beta1/approvals"}; + option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = { + tags: "Approvals"; + summary: "List Approvals"; + description: "List Approvals returns a list of approvals"; + }; } rpc UpdateApproval(UpdateApprovalRequest) returns (UpdateApprovalResponse) { @@ -275,6 +389,11 @@ service GuardianService { post: "/v1beta1/appeals/{id}/approvals/{approval_name}" body: "action" }; + option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = { + tags: "Approvals"; + summary: "Update Approval"; + description: "Update Approval is used to approve or reject a user appeal"; + }; } rpc AddApprover(AddApproverRequest) returns (AddApproverResponse) { @@ -282,22 +401,47 @@ service GuardianService { post: "/v1beta1/appeals/{appeal_id}/approvals/{approval_id}/approvers" body: "*" }; + option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = { + tags: "Approvals"; + summary: "Add Approver"; + description: "Add Approver adds an approver email to an appeal approval step"; + }; } rpc DeleteApprover(DeleteApproverRequest) returns (DeleteApproverResponse) { option (google.api.http) = {delete: "/v1beta1/appeals/{appeal_id}/approvals/{approval_id}/approvers/{email}"}; + option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = { + tags: "Approvals"; + summary: "Delete Approver"; + description: "Delete Approver deletes an approver from an approval"; + }; } rpc ListGrants(ListGrantsRequest) returns (ListGrantsResponse) { option (google.api.http) = {get: "/v1beta1/grants"}; + option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = { + tags: "Grants"; + summary: "List Grants"; + description: "List Grants returns a list of grants"; + }; } rpc ListUserGrants(ListUserGrantsRequest) returns (ListUserGrantsResponse) { option (google.api.http) = {get: "/v1beta1/me/grants"}; + option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = { + tags: "Grants"; + summary: "List User Grants"; + description: "List User Grants returns a list of grants created by the user"; + }; } rpc GetGrant(GetGrantRequest) returns (GetGrantResponse) { option (google.api.http) = {get: "/v1beta1/grants/{id}"}; + option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = { + tags: "Grants"; + summary: "Get Grant"; + description: "Get Grant returns a grant by ID"; + }; } rpc UpdateGrant(UpdateGrantRequest) returns (UpdateGrantResponse) { @@ -305,6 +449,11 @@ service GuardianService { patch: "/v1beta1/grants/{id}" body: "*" }; + option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = { + tags: "Grants"; + summary: "Update Grant"; + description: "Update Grant updates a grant"; + }; } rpc RevokeGrant(RevokeGrantRequest) returns (RevokeGrantResponse) { @@ -312,6 +461,11 @@ service GuardianService { put: "/v1beta1/grants/{id}/revoke" body: "*" }; + option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = { + tags: "Grants"; + summary: "Revoke Grant"; + description: "Revoke Grant revokes a grant"; + }; } rpc RevokeGrants(RevokeGrantsRequest) returns (RevokeGrantsResponse) { @@ -319,6 +473,11 @@ service GuardianService { put: "/v1beta1/grants/revoke" body: "*" }; + option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = { + tags: "Grants"; + summary: "Revoke Grants"; + description: "Revoke Grants revokes a list of grants"; + }; } rpc ImportGrantsFromProvider(ImportGrantsFromProviderRequest) returns (ImportGrantsFromProviderResponse) { @@ -326,6 +485,10 @@ service GuardianService { post: "/v1beta1/grants/import" body: "*" }; + option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = { + tags: "Grants"; + summary: "Import Grants From Provider"; + }; } // Namespace contains information about a tenant @@ -334,14 +497,26 @@ service GuardianService { post: "/v1beta1/namespaces" body: "*" }; + option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = { + tags: "Namespaces"; + summary: "Create Namespace"; + }; } rpc GetNamespace(GetNamespaceRequest) returns (GetNamespaceResponse) { option (google.api.http) = {get: "/v1beta1/namespaces/{id}"}; + option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = { + tags: "Namespaces"; + summary: "Get Namespace"; + }; } rpc ListNamespaces(ListNamespacesRequest) returns (ListNamespacesResponse) { option (google.api.http) = {get: "/v1beta1/namespaces"}; + option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = { + tags: "Namespaces"; + summary: "List Namespaces"; + }; } rpc UpdateNamespace(UpdateNamespaceRequest) returns (UpdateNamespaceResponse) { @@ -349,6 +524,10 @@ service GuardianService { put: "/v1beta1/namespaces/{id}" body: "*" }; + option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = { + tags: "Namespaces"; + summary: "Update Namespace"; + }; } } @@ -625,7 +804,10 @@ message RevokeAppealsResponse { } message CreateAppealRequest { - string account_id = 1; + string account_id = 1 [ + (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = + {description: "Account ID of the user or service account who is creating the appeal"} + ]; message Resource { string id = 1; @@ -633,8 +815,14 @@ message CreateAppealRequest { google.protobuf.Struct options = 3; google.protobuf.Struct details = 4; } - repeated Resource resources = 2; - string account_type = 3; + repeated Resource resources = 2 [ + (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = + {description: "List of resources that the user is requesting access to"} + ]; + string account_type = 3 [ + (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = + {description: "Account type of the user or service account who is creating the appeal. For example for BigQuery and Google Cloud IAM values are \"user\" or \"service_account\""} + ]; string description = 4; } @@ -643,9 +831,17 @@ message CreateAppealResponse { } message ListUserApprovalsRequest { - repeated string statuses = 2; + repeated string statuses = 2 [ + (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = + {description: "List of approval statuses to filter by. Possible values are \"pending\", \"active\", \"rejected\", \"cancelled\", \"terminated\"" + example: "[\"pending\", \"active\"]" + } + ]; repeated string order_by = 3; - string account_id = 4; + string account_id = 4 [ + (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = + {description: "Account ID of the user or service account who is creating the appeal"} + ]; uint32 size = 5 [(validate.rules).uint32 = { gte: 0, ignore_empty: true @@ -691,11 +887,29 @@ message ListApprovalsResponse { message UpdateApprovalRequest { string id = 1; - string approval_name = 2; + string approval_name = 2 [ + (google.api.field_behavior) = REQUIRED, + (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = + { + description: "Name of the approval step" + example: "\"admin_approval\"" + } + ]; message Action { - string action = 1; - string reason = 2; + string action = 1 [ + (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = + { + description: "Action to take on the approval. Possible values are \"approve\" or \"reject\"" + example: "\"approve\"" + } + ]; + string reason = 2 [ + (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = + { + description: "In case an appeal is rejected, the reason is to be updated in this field" + } + ]; } Action action = 3; } @@ -705,9 +919,30 @@ message UpdateApprovalResponse { } message AddApproverRequest { - string appeal_id = 1; - string approval_id = 2; - string email = 3; + string appeal_id = 1 [ + (google.api.field_behavior) = REQUIRED, + (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = + { + description: "UUID of the appeal" + example: "\"f1b9a9a0-1f0b-4b7a-8b0a-9b0a9b0a9b0a\"" + } + ]; + string approval_id = 2 [ + (google.api.field_behavior) = REQUIRED, + (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = + { + description: "Unique identifier or name of the approval" + example: "\"f1b9a9a0-1f0b-4b7a-8b0a-9b0a9b0a9b0a\"" + } + ]; + string email = 3 [ + (google.api.field_behavior) = REQUIRED, + (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = + { + description: "Email of the approver" + example: "\"john@raystack.org\"" + } + ]; } message AddApproverResponse { @@ -868,8 +1103,18 @@ message Provider { ProviderConfig config = 4; - google.protobuf.Timestamp created_at = 5; - google.protobuf.Timestamp updated_at = 6; + google.protobuf.Timestamp created_at = 5 [ + (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = { + description: "Creation time of the provider" + example: "\"2023-01-01T00:00:00Z\"" + } + ]; + google.protobuf.Timestamp updated_at = 6 [ + (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = { + description: "Last update time of the provider" + example: "\"2023-01-01T00:00:00Z\"" + } + ]; } message ProviderType { @@ -1133,8 +1378,18 @@ message Appeal { Resource resource = 10; // optional repeated Approval approvals = 11; - google.protobuf.Timestamp created_at = 12; - google.protobuf.Timestamp updated_at = 13; + google.protobuf.Timestamp created_at = 12 [ + (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = { + description: "Creation time of the appeal" + example: "\"2023-01-01T00:00:00Z\"" + } + ]; + google.protobuf.Timestamp updated_at = 13 [ + (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = { + description: "Last update time of the appeal" + example: "\"2023-01-01T00:00:00Z\"" + } + ]; google.protobuf.Struct details = 17; string account_type = 18; @@ -1156,8 +1411,18 @@ message Approval { uint32 policy_version = 7; repeated string approvers = 8; Appeal appeal = 9; - google.protobuf.Timestamp created_at = 10; - google.protobuf.Timestamp updated_at = 11; + google.protobuf.Timestamp created_at = 10 [ + (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = { + description: "Approval creation timestamp" + example: "\"2023-06-07T05:39:56.961Z\"" + } + ]; + google.protobuf.Timestamp updated_at = 11 [ + (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = { + description: "Approval last update timestamp" + example: "\"2023-06-07T05:39:56.961Z\"" + } + ]; string reason = 12; } @@ -1239,11 +1504,26 @@ message Grant { google.protobuf.Timestamp expiration_date = 8; string appeal_id = 9; string revoked_by = 10; - google.protobuf.Timestamp revoked_at = 11; + google.protobuf.Timestamp revoked_at = 11 [ + (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = { + description: "Timestamp when the grant is revoked" + example: "\"2023-01-01T00:00:00Z\"" + } + ]; string revoke_reason = 12; string created_by = 13; - google.protobuf.Timestamp created_at = 14; - google.protobuf.Timestamp updated_at = 15; + google.protobuf.Timestamp created_at = 14 [ + (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = { + description: "Creation time of the grant" + example: "\"2023-01-01T00:00:00Z\"" + } + ]; + google.protobuf.Timestamp updated_at = 15 [ + (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = { + description: "Last update time of the grant" + example: "\"2023-01-01T00:00:00Z\"" + } + ]; Resource resource = 16; Appeal appeal = 17; @@ -1263,7 +1543,12 @@ message ProviderActivity { repeated string authorizations = 7; string type = 8; google.protobuf.Struct metadata = 9; - google.protobuf.Timestamp created_at = 10; + google.protobuf.Timestamp created_at = 10 [ + (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = { + description: "Creation time of the provider activity" + example: "\"2023-01-01T00:00:00Z\"" + } + ]; Provider provider = 11; Resource resource = 12; string provider_activity_id = 13; @@ -1275,8 +1560,18 @@ message Namespace { string name = 2; string state = 3; google.protobuf.Struct metadata = 4; - google.protobuf.Timestamp created_at = 5; - google.protobuf.Timestamp updated_at = 6; + google.protobuf.Timestamp created_at = 5 [ + (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = { + description: "Creation time of the namespace" + example: "\"2023-01-01T00:00:00Z\"" + } + ]; + google.protobuf.Timestamp updated_at = 6 [ + (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = { + description: "Last update time of the namespace" + example: "\"2023-01-01T00:00:00Z\"" + } + ]; } message CreateNamespaceRequest {