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: verbs 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 parts 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.

Search results