Service Accounts
What are service accounts?
Service accounts are used for Machine to Machine (M2M) authentication and use OIDC federation to log in to Phobos. For instance, they allow a CI/CD pipeline to authenticate and interface with the API.
Service accounts can be scoped to a specific organization or project. Organization-scoped service accounts are accessible to all of the organization's projects. Project-scoped service accounts are only accessible within the project. Service accounts can be added as members with defined roles so that resources (e.g., agents) within the organization or project can use the service accounts.
Check the FAQ to see if there's already an answer.
Authentication
Service accounts use OIDC federation to authenticate. Trust policies define which identity providers (e.g., GitLab CI, GitHub Actions) can issue tokens for the service account, along with bound claims that must match.
Creating a service account
To create a service account, navigate to the target organization or target project and click on Service Accounts from the sidebar. Then click on the Create Service Account button.
Fill in the name, an optional description, Identity Provider information with bound claims, and click Create Service Account.
After creating a service account, it must be added as a member to an organization or project. Adding a service account as a member will allow the organization or project to use the service account for authentication.
Check out Memberships for information on adding a service account as a member. Additionally, see the FAQs for suggestions on roles.
Viewing service account memberships
To view which organizations and projects a service account is a member of, navigate to the service account's details page and select the Memberships tab. This is useful for understanding the scope of a service account's access and for determining who needs Owner permissions to edit it.
Updating a service account
To update a service account, navigate to the Service Account page, select the service account you want to update, and click on the Edit button.
You can update the description and Identity Provider information with bound claims. Click Update Service Account to save the changes.
If the service account is a member of any projects or the parent organization, the caller must have an Owner role in all of those projects and/or the organization to edit the service account. This restriction prevents members with lower roles from escalating access by modifying a service account's trust policy (bound claims), which controls how the service account authenticates. Without this safeguard, a compromised or malicious service account could potentially modify its own authentication requirements.
If the service account is not yet a member of any projects or organization, any caller with sufficient permissions can edit it.
Deleting a service account
To delete a service account, navigate to the Service Account page, select the service account you want to delete, and click on the upside-down caret next to the Edit button. Then click on the Delete Service Account button.
Deleting a service account will break any integrations that rely on it, such as CI/CD pipelines.
Frequently Asked Questions (FAQ)
Who can create a service account?
Any member of the target organization or project with a role of Owner, Release Manager, or Developer can create a service account. Viewers cannot create a service account.
Who can delete a service account?
Any member of the target organization or project with a role of Owner, Release Manager, or Developer can delete a service account. Unlike editing, deleting a service account does not require an Owner role in all projects or the organization where the service account is a member.
How do I use a service account with the Phobos CLI?
See the CLI documentation for more information.
Why is my service account not working?
Please make sure that the service account is a member of the organization or the project and has the necessary role assigned to it. Also, ensure that the service account has the correct Identity Provider information with bound claims.
Should I just give my service account an Owner role?
No, it is not recommended to give a service account an Owner role. Generally, a Developer role is sufficient for most use cases. An Owner role will allow the service account to manage the organization, its members, and arbitrarily perform any action; this goes against the principle of least privilege.
Can a service account from one organization access resources in another organization?
No, a service account can only access resources within the organization it is a member of.
I don't want to give my organization-scoped service account access to all its projects. What should I do?
Organization-level memberships are inherited by all projects within the organization. If you want to limit a service account's access, you have two options:
- Create a service account in each project that needs one, so each is scoped to only that project.
- Create an organization-scoped service account but only add it as a member to the specific projects that need it, rather than at the organization level.
Will the CLI periodically renew the token for the service account?
Yes, the CLI will periodically renew the token for the service account. The token should be renewed a short period of time before it expires.