Managing service accounts

A service account is an account for software, such as a GitHub Actions workflow or a script with an API key. It has an owner: you, or an organization that you own or maintain. source.coop must first let that account own service accounts.

A service account's ID is the owner's ID, then --, then its own name: my-org--nightly-sync. AWS tools use this ID: role-to-assume: arn:aws:iam::my-org--nightly-sync:role/FullAccess.

source-coop service-account shows a service account as the web UI does: what it is, how it signs in, and the products it can use.

List and view

source-coop service-account list my-org             # my-org's service accounts (yours, with no owner)
source-coop service-account list my-org --no-pager  # print directly, not in the pager
source-coop service-account list my-org -i          # move through them full screen (keys as for products)
source-coop service-account view my-org--nightly-sync          # --json adds `trusts`, `keys` and `memberships`
source-coop service-account view my-org--nightly-sync -w       # open its page in the browser

view shows who the service account is, how it signs in and the products it can reach. --json adds trusts, keys and memberships.

list -i uses the same keys as product list -i. On a service account's screen, e edits it and d deletes it.

Create

source-coop service-account create                  # asks for all values, as the web form does
source-coop service-account create my-org--nightly-sync --name "Nightly sync" \
    --github my-org/data --branch main --access my-org/my-data=write

create takes values as flags, as a JSON object with --from-file, or both:

• Flags: --name, one --github workflow, a --key with --expires and --out, and --access (one or more).
• JSON uses the API's fields: name, local_id, github_subjects, key, grants.

At a terminal, create asks for the missing values: the owner, the name, the ID (made from the name), workflows and an API key, and products. Then it shows all values, with the condition that each workflow must match, and asks you to confirm.

If create issues a key, it gives you the key as sign-in add does. But stdout gets the account's ID, not the key. To keep the key, use --out or --json.

create and edit print the service account's ID on stdout. Thus id=$(source-coop service-account create …) works. Going back, drafts, the sign-in check and --yes work as for products.

Edit

source-coop service-account edit my-org--nightly-sync --name "Nightly sync"
source-coop service-account edit my-org--nightly-sync            # a form of its name and products
source-coop service-account edit my-org--nightly-sync --disable   # --enable lets it sign in again

--disable stops all sign-ins as the service account. It keeps its sign-ins and products. --enable lets its workflows and its keys that are not revoked sign in again.

With no flags, edit opens a form of its name and products (see Access to products).

Delete

source-coop service-account delete my-org--nightly-sync           # asks you to type its ID

delete removes the service account, its sign-ins and its access to products. Type its ID to confirm, or use --yes.

Access to products

A service account can read, or read and write, its owner's products. Each grant is a usual membership of the product.

• create --access gives access when you create the service account.
• edit --access gives access, changes the role, or removes access (=none).

source-coop service-account edit my-org--nightly-sync --access my-org/my-data=write --access my-org/old-data=none

If the product already has that role, or has no access to remove, nothing changes. Thus you can run an edit two times safely.

With no flags, edit opens a full-screen form with Name, then the products under Can reach, each with its role:

• ↑ ↓ moves. Enter changes the selected row: the name, or the access to a product (Read, Read and write, or No access).
• Grant a product… adds one of the owner's other products.
• A changed row shows its old value.
• s, or Enter on Save changes, shows the changes and asks you to confirm. ← goes back to the form.
• Esc or ← on the form cancels. If you changed a row, the form asks first.

--disable and --enable are flags only.