Service accounts
A service account is a special type of account, distinct from a user account, which you can use to authenticate and interact with SpatialOS.
Service accounts consist of several components:
- a descriptive name outlining what the service account is used for
- a project name which is the name of the project associated with the service account - anyone who is part of the project is able to view basic details about the service account
- an expiry time at which point the service account will become invalid
- a list of permissions which specify what the service account can do
- a refresh token which you provide as authentication to services
- an ID used to update and delete the service account
When running automated jobs such as performing game maintenance, you should use a refresh token belonging to a service account instead of your personal refresh token.
You can create and manage service accounts using the Platform SDK.
Using service accounts
As a rule of thumb, if you are performing an action yourself, you should use your own refresh token for authentication. If you are providing a refresh token as a parameter or variable in a script or automated task, create a service account with the required permissions and use that refresh token instead.
Create a separate service account for each individual script or task you need to perform. If you create a ‘master’ service account for all of your scripts, you risk exposing unnecessary permissions to parts of your code and causing a security risk. Additionally, a more granular service account structure allows you to revoke one of your services access by deleting the service account without affecting your other services.
Permissions
Permissions are tied to a service account and determine what it can read, write, and grant others access to.
A single permission comprises two components: verb
s and path
.
Verbs
Verbs are how you specify what a service account can access for a given permission. There are three verbs.
Verb | What it means |
---|---|
Read |
Read (including listing) from a resource |
Write |
Write (including creating and deleting) to a resource |
Grant |
Grant permissions for a resource to service accounts |
Think carefully about which verbs you assign to a permission. For security reasons, you can’t give Grant
permissions to a service account. Only users can possess a Grant
permission.
Path
The path is a list of strings known as part
s which specify the services or projects the service account has access to.
Path | What it means |
---|---|
prj , my_project , * |
Access the project with name my_project |
srv , * |
Access metrics services |
More paths will become available in later versions.
Now that you have seen both verbs and paths, you can construct a permission. For example, you might want to use the deployment service to manage to the deployments for your game in the project called my_project
. In this case, you need read and write access to the path with parts prj
, and my_project
. Using the Platform SDK, this is represented as:
var perm = new Permission
{
Parts = {new RepeatedField<string> {"prj", "my_project", "*"}},
Verbs =
{
new RepeatedField<Permission.Types.Verb>
{
Permission.Types.Verb.Read,
Permission.Types.Verb.Write
}
}
};
Lifetime
When you create a service account, you should also provide a reasonable Lifetime
which is a duration determining when the service account will expire and become invalid.
If a service account is used after it has expired, the refresh token will be invalid and will not function as expected.