Replaces `may` with `can` (ability or permission) or `might` (possibility), following `word-choice.md#choose-words-that-have-one-meaning`. The Vale findings spike review marked every `may` row valid. - 247 lines in 110 files: 75 became `can` and 162 became `might`. The rest are small rewordings, such as "may wish" becoming "might want". - Applied the reviewer notes: - `.style/content-guidelines.md`: "docs may be written ahead" is now "you can write docs ahead", which also drops the passive voice. - `admin/external-auth.md`: now "You can grant access to a subset of repositories.", so the sentence doesn't end on a preposition. - Also fixed a typo in `gcp-to-aws.md`: "may needed" is now "might need". ## Left as-is - **`admin/setup/configuration-reference.md` (7 lines):** this page is generated from `codersdk` deployment options (`<!-- DO NOT EDIT | GENERATED CONTENT -->`), so the fix belongs in the Go option descriptions, followed by `make gen`. - **Text that quotes the product:** - `admin/monitoring/health-check.md:196` matches the derphealth message. - The heading at `templates/troubleshooting.md:45`, the first "may" on line 47, and the link on line 67 match the web terminal's "your workspace may be incomplete" warning and its anchor. - `admin/integrations/oauth2-provider/troubleshooting.md:269` quotes a server error. The changed files have no new findings from other rules. --- AI-generated by Superblink on behalf of @nickvigilante. --------- Co-authored-by: coder[bot] <137810501+coder[bot]@users.noreply.github.com>
240 lines
9.2 KiB
Markdown
240 lines
9.2 KiB
Markdown
---
|
|
title: Persistent shared workspaces with service accounts
|
|
---
|
|
|
|
> [!NOTE]
|
|
> This guide requires a [Premium license](https://coder.com/pricing#compare-plans) because service accounts are a Premium feature.
|
|
> For more details, [contact your account team](https://coder.com/contact).
|
|
|
|
This guide walks through setting up a long-lived workspace that is owned by a service account and shared with a rotating set of users.
|
|
Because no single person owns the workspace, it persists across team changes and every user authenticates as themselves.
|
|
|
|
This pattern is useful for any scenario where a workspace outlives the people who use it:
|
|
|
|
- **On-call rotations**:
|
|
Engineers share a workspace pre-loaded with runbooks, dashboards, and monitoring tools.
|
|
Access rotates with the shift schedule.
|
|
- **Shared staging or QA**:
|
|
A team workspace hosts a persistent staging environment.
|
|
Quality assurance (QA) testers and reviewers are added and removed as sprints change.
|
|
- **Pair programming**:
|
|
A service-account-owned workspace gives two or more developers a shared environment without either one owning (and accidentally deleting) it.
|
|
- **Contractor onboarding**:
|
|
An external team gets scoped access to a workspace for the duration of an engagement, then access is revoked.
|
|
|
|
The steps below use an on-call site reliability engineering (SRE) workspace as a running example, but the same commands apply to any of the scenarios above.
|
|
Substitute the usernames, group names, and template to match your use case.
|
|
|
|
## Prerequisites
|
|
|
|
- A running Coder deployment (v2.32+) with workspace sharing enabled.
|
|
Sharing is on by default for open source software (OSS).
|
|
Premium deployments might require [admin configuration](shared-workspaces.md#policies).
|
|
- The [Coder CLI](../install/index.md) installed and authenticated.
|
|
- An account with the `Owner` or `User Admin` role.
|
|
- [OpenID Connect (OIDC) authentication](../admin/users/oidc-auth/index.md) configured so shared users log in with their corporate single sign-on (SSO) identity.
|
|
Configure [refresh tokens](../admin/users/oidc-auth/refresh-tokens.md) to prevent session timeouts during long work sessions.
|
|
- A [wildcard access URL](../admin/networking/wildcard-access-url.md) configured (for example, `*.coder.example.com`) so that shared users can access workspace apps without a 404.
|
|
- (Recommended) [IdP Group Sync](../admin/users/idp-sync.md#group-sync) configured if your identity provider manages group membership for the teams that will share the workspace.
|
|
|
|
## 1. Create a service account
|
|
|
|
Create a dedicated service account that will own the shared workspace.
|
|
Service accounts are non-human accounts intended for automation and shared ownership.
|
|
Because no individual user owns the workspace, there are no personal credentials to expose and the shared environment is not affected when any user leaves the team or the organization.
|
|
|
|
```sh
|
|
# On-call example — substitute a name that fits your use case
|
|
coder users create \
|
|
--username oncall-sre \
|
|
--service-account
|
|
```
|
|
|
|
Git in the workspace uses the service account's identity and credentials for every shared user.
|
|
To set up repository access and let users commit as themselves, refer to [Git identity and credentials](./shared-workspaces.md#git-identity-and-credentials).
|
|
|
|
## 2. Generate an API token for the service account
|
|
|
|
Generate a long-lived API token so you can create and manage workspaces on behalf of the service account:
|
|
|
|
```sh
|
|
coder tokens create \
|
|
--user oncall-sre \
|
|
--name oncall-automation \
|
|
--lifetime 8760h
|
|
```
|
|
|
|
Store this token securely (for example, in a secrets manager like Vault or AWS Secrets Manager).
|
|
|
|
> [!IMPORTANT]
|
|
> Never distribute this token to end users.
|
|
> The token is for workspace administration only.
|
|
> Shared users authenticate as themselves and reach the workspace through sharing.
|
|
|
|
## 3. Create the workspace
|
|
|
|
Authenticate as the service account and create the workspace:
|
|
|
|
```sh
|
|
export CODER_SESSION_TOKEN="<token-from-step-2>"
|
|
|
|
coder create oncall-sre/oncall-workspace \
|
|
--template your-oncall-template \
|
|
--use-parameter-defaults \
|
|
--yes
|
|
```
|
|
|
|
> [!TIP]
|
|
> Design a dedicated template for the workspace with the tools your team needs pre-installed (for example, monitoring dashboards for on-call, test runners for QA).
|
|
> Set `subdomain = true` on workspace apps so that shared users can access web-based tools without a 404.
|
|
> See [Access workspace apps in shared workspaces](shared-workspaces.md#access-workspace-apps-in-shared-workspaces).
|
|
|
|
## 4. Share the workspace
|
|
|
|
Use `coder sharing share` to grant access to users who need the workspace:
|
|
|
|
```sh
|
|
coder sharing share oncall-sre/oncall-workspace --user alice
|
|
```
|
|
|
|
This gives `alice` the default `use` role, which allows connection via SSH and workspace apps, starting and stopping the workspace, and viewing logs and stats.
|
|
|
|
To grant `admin` permissions (which includes all `use` permissions as well as renaming, updating, and inviting others to join with the `use` role):
|
|
|
|
```sh
|
|
coder sharing share oncall-sre/oncall-workspace --user alice:admin
|
|
```
|
|
|
|
To share with multiple users at once:
|
|
|
|
```sh
|
|
coder sharing share oncall-sre/oncall-workspace --user alice:admin,bob
|
|
```
|
|
|
|
To share with an entire Coder group:
|
|
|
|
```sh
|
|
coder sharing share oncall-sre/oncall-workspace --group sre-oncall
|
|
```
|
|
|
|
> [!NOTE]
|
|
> Groups can be synced from your identity provider using [IdP Sync](../admin/users/idp-sync.md#group-sync).
|
|
> If your IdP already manages team membership, sharing with a group is the simplest approach.
|
|
|
|
## 5. Rotate access
|
|
|
|
When team membership changes, remove outgoing users and add incoming ones:
|
|
|
|
```sh
|
|
# Remove outgoing user
|
|
coder sharing remove oncall-sre/oncall-workspace --user alice
|
|
|
|
# Add incoming user
|
|
coder sharing share oncall-sre/oncall-workspace --user carol
|
|
```
|
|
|
|
> [!IMPORTANT]
|
|
> The workspace must be restarted for user removal to take effect.
|
|
|
|
Verify current sharing status at any time:
|
|
|
|
```sh
|
|
coder sharing status oncall-sre/oncall-workspace
|
|
```
|
|
|
|
For every subcommand and flag, see the [`coder sharing` reference](../reference/cli/sharing/index.md).
|
|
|
|
## 6. Automate access changes (optional)
|
|
|
|
For use cases with frequent rotation (such as on-call shifts), you can integrate the share/remove commands into external tooling like PagerDuty, Opsgenie, or a cron job.
|
|
|
|
### Rotation script
|
|
|
|
```sh
|
|
#!/bin/bash
|
|
# rotate-access.sh
|
|
# Usage: ./rotate-access.sh <outgoing-user> <incoming-user>
|
|
|
|
WORKSPACE="oncall-sre/oncall-workspace"
|
|
OUTGOING="$1"
|
|
INCOMING="$2"
|
|
|
|
if [ -n "$OUTGOING" ]; then
|
|
echo "Removing access for $OUTGOING..."
|
|
coder sharing remove "$WORKSPACE" --user "$OUTGOING"
|
|
fi
|
|
|
|
echo "Granting access to $INCOMING..."
|
|
coder sharing share "$WORKSPACE" --user "$INCOMING"
|
|
|
|
echo "Restarting workspace to apply changes..."
|
|
coder restart "$WORKSPACE" --yes
|
|
|
|
echo "Current sharing status:"
|
|
coder sharing status "$WORKSPACE"
|
|
```
|
|
|
|
### Group-based rotation with IdP Sync
|
|
|
|
If your identity provider manages group membership (for example, an `sre-oncall` group in Okta or Azure Active Directory (AD)), you can skip manual share/remove commands entirely:
|
|
|
|
1. Configure [Group Sync](../admin/users/idp-sync.md#group-sync) to synchronize the group from your IdP to Coder.
|
|
|
|
1. Share the workspace with the group once:
|
|
|
|
```sh
|
|
coder sharing share oncall-sre/oncall-workspace --group sre-oncall
|
|
```
|
|
|
|
1. When your IdP rotates group membership, Coder group membership updates on next login.
|
|
|
|
All current members have access.
|
|
Removed members lose access after a workspace restart.
|
|
|
|
<a id="finding-shared-workspaces"></a>
|
|
|
|
## Find shared workspaces
|
|
|
|
Shared users can find workspaces shared with them:
|
|
|
|
```sh
|
|
# List all shared workspaces you can access, including your own
|
|
coder list --search shared:true
|
|
|
|
# List workspaces shared with you
|
|
coder list --search shared_with_user:me
|
|
|
|
# List workspaces shared with a specific user
|
|
coder list --search shared_with_user:alice
|
|
|
|
# List workspaces shared with a specific group
|
|
coder list --search shared_with_group:sre-oncall
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
### Shared user sees 404 on workspace apps
|
|
|
|
Workspace apps using path-based routing block non-owners by default.
|
|
Configure a [wildcard access URL](../admin/networking/wildcard-access-url.md) and set `subdomain = true` on the workspace app in your template.
|
|
|
|
### Removed user still has access
|
|
|
|
Access removal requires a workspace restart.
|
|
Run `coder restart <workspace>` after removing a user or group.
|
|
|
|
### Group sync not updating membership
|
|
|
|
Group membership changes in your IdP are not reflected until the user logs out and back in.
|
|
Group sync runs at login time, not on a polling schedule.
|
|
Check the logs from `coderd`, the process that runs the control plane, with `CODER_LOG_FILTER=".*userauth.*|.*groups returned.*"` for details.
|
|
See [Troubleshooting group sync](../admin/users/idp-sync.md#troubleshooting-grouproleorganization-sync) for more information.
|
|
|
|
## Next steps
|
|
|
|
- [Shared Workspaces](shared-workspaces.md): full reference for workspace sharing features and UI
|
|
- [IdP Sync](../admin/users/idp-sync.md): group, role, and organization sync configuration
|
|
- [Configuring Okta](../admin/users/oidc-auth/configuring-okta.md): Okta-specific OIDC setup with custom claims and scopes
|
|
- [Security Best Practices](../admin/security/security-best-practices.md): deployment-wide security hardening
|
|
- [Sessions and Tokens](../admin/users/sessions-tokens.md): API token management and scoping
|