From 3b7c8536acd6f8801e8925824b57a3fee5fa800d Mon Sep 17 00:00:00 2001 From: Kent Rancourt Date: Tue, 19 Dec 2023 17:01:41 -0500 Subject: [PATCH] document sso user --> serviceaccount mappings Signed-off-by: Kent Rancourt --- .../30-managing-user-permissions.md | 112 ++++++++++++++++++ 1 file changed, 112 insertions(+) create mode 100644 docs/docs/30-how-to-guides/30-managing-user-permissions.md diff --git a/docs/docs/30-how-to-guides/30-managing-user-permissions.md b/docs/docs/30-how-to-guides/30-managing-user-permissions.md new file mode 100644 index 0000000000..ad43c9be33 --- /dev/null +++ b/docs/docs/30-how-to-guides/30-managing-user-permissions.md @@ -0,0 +1,112 @@ +--- +description: Learn how to manage user permissions +sidebar_label: Managing user permissions +--- + +# Managing User Permissions + +Kargo is typically configured to support single-sign-on (SSO) using an external +identity provider that implements the +[OpenID Connect](https://openid.net/developers/how-connect-works/) protocol. + +:::info +Refer to +[the advanced section of the installation guide](./10-installing-kargo.md#advanced-installation) +for more details on how to configure Kargo to use an external identity provider. +::: + +Kargo also implements authorization of all user actions using pure Kubernetes +[RBAC](https://kubernetes.io/docs/reference/access-authn-authz/rbac/). i.e. +Permission to perform various actions on various Kargo resources is therefore +granted via `RoleBinding` resources that associate users or `ServiceAccount` +resources with `Role` resources. + +Because Kargo users log into the Kargo CLI or UI via SSO, their identifies are +not known to Kargo's underlying Kubernetes cluster. This represents an +impediment to using Kubernetes RBAC to authorize the actions of such users. + +Kargo answers this challenge through a scheme that permits users to be mapped +to zero or more Kubernetes `ServiceAccount` resources. The remainder of this +page describes how to create those mappings. + +## User to `ServiceAccount` Mappings + +Whether logged into the Kargo CLI or UI, Kargo users are interacting with Kargo +via the Kargo API server. The Kargo API server authenticates users via a bearer +token issued by the external identity provider. On every request, the Kargo +API server validates and decodes the token to obtain trusted information about +the user. This includes: + +* The user's unique identifier (the standard OpenID Connect `sub` claim) +* The user's email address (the standard OpenID Connect `email` claim) +* Groups to which the user belongs (the non-standard, but widely supported + `groups` claim) + +Also at the time of authentication, the Kargo API server queries the Kubernetes +API server to obtain a list of all `ServiceAccount` resources to which the user +has been mapped. Kargo typically restricts this search to `ServiceAccount` resources +in Kargo project namespaces only (i.e. only those labeled with +`kargo.akuity.io/project: "true"`). Refer to the next section for exceptions to +this rule. + +ServiceAccount resources may be mapped to users through the use of three +different annotations: + +* `rbac.kargo.akuity.io/sub`: This annotation's value may be a comma-delimited + list of user identifiers. All users in the list will be mapped to the + `ServiceAccount`. + +* `rbac.kargo.akuity.io/email`: This annotation's value may be a comma-delimited + list of user email addresses. All users in the list having one of the listed + email addresses will be mapped to the `ServiceAccount`. + +* `rbac.kargo.akuity.io/groups`: This annotation's value may be a + comma-delimited list of group identifiers. All users in the list belonging to + one or more of the listed groups will be mapped to the `ServiceAccount`. + +In the following example, the `ServiceAccount` resource is mapped to all of: + +* A user identified as `bob`. +* A user with the email address `alice@example.com`. +* All users in the group `devops`. + +```yaml +apiVersion: v1 +kind: ServiceAccount +metadata: + name: admin + namespace: kargo-demo + annotations: + rbac.kargo.akuity.io/sub: bob + rbac.kargo.akuity.io/email: alice@example.com + rbac.kargo.akuity.io/groups: devops +``` + +:::note +Kargo has no built-in functionality for managing these `ServiceAccount` +resources and their annotations at this time, meaning they must currently be +managed through other means, such as `kubectl` or Argo CD. +::: + +A user may be mapped to multiple `ServiceAccount` resources. A user's effective +permissions are therefore the union of the permissions associated with all such +`ServiceAccount` resources. + +## Global Mappings + +In cases where certain, broad sets of permissions may be required by a large +numbers of users, the administrator/operator installing Kargo may opt-in to +designating one or more namespaces as homes for "global" `ServiceAccount` +resources using the `api.oidc.globalServiceAccounts` setting in Kargo's Helm +chart. Refer to +[the advanced section of the installation guide](./10-installing-kargo.md#advanced-installation) +for more details. + +Note that `ServiceAccount` resources in designated namespaces are not _truly_ +global because they are _still_ mapped to users according to the rules described +in the previous section. + +Making use of this feature could be, for instance, a convenient method of +granting read-only access to all Kargo resources in all projects to all users +within an organization. Additional permissions may then be granted to users on a +project-by-project basis.