6b53766aa6
* internal/gen: better API docs Add various pieces of metadata that can be used by the API docs renderer. Improve the service labels by specifying explicit tags. Specify error responses. Specify version at generation time. * internal/gen: add better errors The default error entry is now used to cover all errors, as adding a new error for every possible status code was a bit much. This also properly includes the real error type now! * Add various pieces of metadata that can be used by the API docs renderer. Improve the service labels by specifying explicit tags. * make auth method API docs * make API docs better * make auth methods API docs nicer * internal/gen: better attribute examples Replace Output Only comments with a field behavior annotation in accounts. Mark some fields as required. Add elaborate description for attributes. * Make API docs better * Make API docs better * Make API docs better * internal/proto: regenerate files * internal/proto: finish off account service * Make API docs better * internal/proto: add better API docs for aliases * Tidy up service descriptions * Added description for Boundary controller API doc * internal/gen: add better API intro Copy parts of the API docs into the description * sdk: add openapi dependency * internal/gen: move global API doc to separate file * internal/gen: remove required annotations Unfortunately, while these help with the creating of resources, they still appear required in contexts where they are not, such as when updating a resource. * Review comments --------- Co-authored-by: jigar-hashicorp <jigar.shah@hashicorp.com> Co-authored-by: Isaac Christian (he/him) <112639904+isaacchristian@users.noreply.github.com>
228 lines
8.8 KiB
Protocol Buffer
228 lines
8.8 KiB
Protocol Buffer
// Copyright (c) HashiCorp, Inc.
|
|
// SPDX-License-Identifier: MPL-2.0
|
|
|
|
syntax = "proto3";
|
|
|
|
package controller.api.resources.accounts.v1;
|
|
|
|
import "controller/api/resources/scopes/v1/scope.proto";
|
|
import "controller/custom_options/v1/options.proto";
|
|
import "google/api/field_behavior.proto";
|
|
import "google/api/visibility.proto";
|
|
import "google/protobuf/struct.proto";
|
|
import "google/protobuf/timestamp.proto";
|
|
import "google/protobuf/wrappers.proto";
|
|
import "protoc-gen-openapiv2/options/annotations.proto";
|
|
|
|
option go_package = "github.com/hashicorp/boundary/sdk/pbs/controller/api/resources/accounts;accounts";
|
|
|
|
// Account contains all fields related to an account resource
|
|
message Account {
|
|
// The ID of the account.
|
|
string id = 10 [(google.api.field_behavior) = OUTPUT_ONLY]; // @gotags: `class:"public" eventstream:"observation"`
|
|
|
|
// Scope information for the account.
|
|
resources.scopes.v1.ScopeInfo scope = 20 [(google.api.field_behavior) = OUTPUT_ONLY];
|
|
|
|
// Optional name for identification purposes.
|
|
google.protobuf.StringValue name = 30 [
|
|
(custom_options.v1.generate_sdk_option) = true,
|
|
(custom_options.v1.mask_mapping) = {
|
|
this: "name"
|
|
that: "Name"
|
|
}
|
|
]; // @gotags: `class:"public"`
|
|
|
|
// Optional user-set description for identification purposes.
|
|
google.protobuf.StringValue description = 40 [
|
|
(custom_options.v1.generate_sdk_option) = true,
|
|
(custom_options.v1.mask_mapping) = {
|
|
this: "description"
|
|
that: "Description"
|
|
}
|
|
]; // @gotags: `class:"public"`
|
|
|
|
// The time this resource was created.
|
|
google.protobuf.Timestamp created_time = 50 [
|
|
json_name = "created_time",
|
|
(google.api.field_behavior) = OUTPUT_ONLY
|
|
]; // @gotags: `class:"public" eventstream:"observation"`
|
|
|
|
// The time this resource was last updated.
|
|
google.protobuf.Timestamp updated_time = 60 [
|
|
json_name = "updated_time",
|
|
(google.api.field_behavior) = OUTPUT_ONLY
|
|
]; // @gotags: `class:"public" eventstream:"observation"`
|
|
|
|
// Version is used in mutation requests, after the initial creation, to ensure this resource has not changed.
|
|
// The mutation fails if the version does not match the latest known good version.
|
|
// Version is not required when you create an account.
|
|
uint32 version = 70; // @gotags: `class:"public"`
|
|
|
|
// The type of this account. If you do not set an account type, Boundary infers it from the type of the auth method.
|
|
string type = 80; // @gotags: `class:"public" eventstream:"observation"`
|
|
|
|
// The ID of the auth method that is associated with this account.
|
|
string auth_method_id = 90 [
|
|
json_name = "auth_method_id",
|
|
(custom_options.v1.subtype_source_id) = true
|
|
]; // @gotags: `class:"public" eventstream:"observation"`
|
|
|
|
oneof attrs {
|
|
// The attributes that are applicable for the specific account type.
|
|
google.protobuf.Struct attributes = 100 [
|
|
(custom_options.v1.generate_sdk_option) = true,
|
|
(custom_options.v1.subtype) = "default",
|
|
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
|
|
example: "{\"login_name\": \"login_name\"}",
|
|
description:
|
|
"The attributes that are applicable for the specific account type. "
|
|
"The schema of this field depends on the type of the auth method "
|
|
"that you create the account in.\n"
|
|
"For password auth methods, the parameters are:\n"
|
|
"```json\n"
|
|
"{\n"
|
|
" \"login_name\": \"login_name\",\n"
|
|
" \"password\": \"password\"\n"
|
|
"}\n"
|
|
"```\n"
|
|
"For OIDC auth methods, the parameters are:\n"
|
|
"```json\n"
|
|
"{\n"
|
|
" \"issuer\": \"issuer\",\n"
|
|
" \"subject\": \"subject\",\n"
|
|
" \"full_name\": \"full_name\",\n"
|
|
" \"email\": \"email\",\n"
|
|
" \"token_claims\": {},\n"
|
|
" \"userinfo_claims\": {}\n"
|
|
"}\n"
|
|
"```\n"
|
|
"For LDAP auth methods, the parameters are:\n"
|
|
"```json\n"
|
|
"{\n"
|
|
" \"login_name\": \"login_name\",\n"
|
|
" \"full_name\": \"full_name\",\n"
|
|
" \"email\": \"email\",\n"
|
|
" \"dn\": \"dn\",\n"
|
|
" \"member_of_groups\": [\"member_of_groups\"]\n"
|
|
"}\n"
|
|
"```\n"
|
|
}
|
|
];
|
|
PasswordAccountAttributes password_account_attributes = 101 [
|
|
(google.api.field_visibility).restriction = "INTERNAL",
|
|
(custom_options.v1.generate_sdk_option) = true,
|
|
(custom_options.v1.subtype) = "password"
|
|
];
|
|
OidcAccountAttributes oidc_account_attributes = 102 [
|
|
(google.api.field_visibility).restriction = "INTERNAL",
|
|
(custom_options.v1.generate_sdk_option) = true,
|
|
(custom_options.v1.subtype) = "oidc"
|
|
];
|
|
LdapAccountAttributes ldap_account_attributes = 103 [
|
|
(google.api.field_visibility).restriction = "INTERNAL",
|
|
(custom_options.v1.generate_sdk_option) = true,
|
|
(custom_options.v1.subtype) = "ldap"
|
|
];
|
|
}
|
|
|
|
// Indicates the IDs of the managed groups that currently contain this account
|
|
repeated string managed_group_ids = 110 [
|
|
json_name = "managed_group_ids",
|
|
(google.api.field_behavior) = OUTPUT_ONLY
|
|
]; // @gotags: `class:"public" eventstream:"observation"`
|
|
|
|
// The available actions on this resource for this user.
|
|
repeated string authorized_actions = 300 [
|
|
json_name = "authorized_actions",
|
|
(google.api.field_behavior) = OUTPUT_ONLY
|
|
]; // @gotags: `class:"public"`
|
|
}
|
|
|
|
// Attributes associated only with accounts with type "password".
|
|
message PasswordAccountAttributes {
|
|
// The login name of this account. This is unique per auth method.
|
|
string login_name = 10 [
|
|
json_name = "login_name",
|
|
(custom_options.v1.generate_sdk_option) = true,
|
|
(custom_options.v1.mask_mapping) = {
|
|
this: "attributes.login_name"
|
|
that: "LoginName"
|
|
}
|
|
]; // @gotags: `class:"sensitive"`
|
|
|
|
// The password for this account.
|
|
google.protobuf.StringValue password = 20 [(custom_options.v1.generate_sdk_option) = true]; // @gotags: `class:"secret"`
|
|
}
|
|
|
|
// Attributes associated only with accounts with type "oidc".
|
|
message OidcAccountAttributes {
|
|
// issuer is a case sensitive URL that maps to the OIDC iss claim.
|
|
// This value is immutable after creation time.
|
|
string issuer = 80 [
|
|
json_name = "issuer",
|
|
(custom_options.v1.generate_sdk_option) = true
|
|
]; // @gotags: `class:"public"`
|
|
|
|
// subject is a case sensitive string that maps to the OIDC sub claim.
|
|
// This value is immutable after creation time.
|
|
string subject = 90 [
|
|
json_name = "subject",
|
|
(custom_options.v1.generate_sdk_option) = true
|
|
]; // @gotags: `class:"public"`
|
|
|
|
// A string that maps to the OIDC name claim.
|
|
string full_name = 100 [
|
|
json_name = "full_name",
|
|
(google.api.field_behavior) = OUTPUT_ONLY
|
|
]; // @gotags: `class:"public"`
|
|
|
|
// A string that maps to the OIDC email claim.
|
|
string email = 110 [(google.api.field_behavior) = OUTPUT_ONLY]; // @gotags: `class:"public"`
|
|
|
|
// The marshaled claims from the token.
|
|
google.protobuf.Struct token_claims = 120 [(google.api.field_behavior) = OUTPUT_ONLY];
|
|
|
|
// The marshaled claims from userinfo.
|
|
google.protobuf.Struct userinfo_claims = 130 [(google.api.field_behavior) = OUTPUT_ONLY];
|
|
}
|
|
|
|
// Attributes associated only with accounts with type "ldap".
|
|
message LdapAccountAttributes {
|
|
// login_name of the authenticated user. This is the login_name (or username)
|
|
// entered by the user when authenticating (typically the uid or cn
|
|
// attribute). Account login names must be lower case.
|
|
string login_name = 100 [
|
|
json_name = "login_name",
|
|
(custom_options.v1.generate_sdk_option) = true,
|
|
(custom_options.v1.mask_mapping) = {
|
|
this: "attributes.login_name"
|
|
that: "LoginName"
|
|
}
|
|
]; // @gotags: `class:"sensitive"`
|
|
|
|
// A string that maps to the name attribute for the
|
|
// authenticated user. This attribute is updated every time a user
|
|
// successfully authenticates.
|
|
string full_name = 110 [
|
|
json_name = "full_name",
|
|
(google.api.field_behavior) = OUTPUT_ONLY
|
|
]; // @gotags: `class:"sensitive"`
|
|
|
|
// A string that maps to the email address attribute for
|
|
// the authenticated user. This attribute is updated every time a user
|
|
// successfully authenticates.
|
|
string email = 120 [(google.api.field_behavior) = OUTPUT_ONLY]; // @gotags: `class:"sensitive"`
|
|
|
|
// The distinguished name authenticated user's entry. Will
|
|
// be null until the user's first successful authentication. This attribute
|
|
// is updated every time a user successfully authenticates.
|
|
string dn = 130 [(google.api.field_behavior) = OUTPUT_ONLY]; // @gotags: `class:"public"`
|
|
|
|
// The json marshalled groups the
|
|
// authenticated user is a member of. Will be null until the user's first
|
|
// successful authentication. This attribute is updated every time a user
|
|
// successfully authenticates.
|
|
repeated string member_of_groups = 140 [(google.api.field_behavior) = OUTPUT_ONLY]; // @gotags: `class:"public"`
|
|
}
|