How Authentication Works¶
The authentication system uses the User, Role, and Tenant objects to define a multi-tenant RBAC system.
User tokens are created by accessing
By default, a token created
using this method can act on behalf of user. This includes rights for
the user to get information about themself, change their password, and
fetch a token for themselves, and any access granted by additional roles
the user has. Users can restrict access that a token generated in this
method by passing an optional comma-seperated list of Roles as a
parameter during the API request, and any requested Roles that would
increase the scope of the allowed Claims will be silently dropped.
Certain common machine usage patterns (discovery, running tasks, etc.) also need to interact with the API, and hence need a Token that authorizes them to perform those actions. These tokens have a fixed set of permissions:
- Machine Discovery: This token has the ability to create and get Machines, and nothing else. It is needed to allow Sledgehammer to create a machine for itself during initial system discovery.
- Machine Operations: This token gives a Machine the ability to modify itself, get stages and tasks, create events, create a reservation and modify a reservation for the machine's address, and create and manage Jobs for itself.
These machine tokens are generated as part of template expansion via the
.GenerateToken command (which generates tokens that expire according to
the unknownTokenTimeout and knownTokenTimeout preferences), and the
.GenerateInfiniteToken command, which generates a Machine Operations
token that expires in 3 years and is intended to grant long-term access
for the task runner. These tokens cannot be generated by any other
How Tokens Are Checked¶
- A request is made to the API. If the request contains
Authorization: Bearer, that token is used. If the request contains
Authorization: Basic, the contained username/password is checked and used to create a one-use Token.
- Claims are created based on the API path requested and the HTTP
method. For example:
GET /api/v3/userscreates a Claim of
GET /api/v3/users/bobcreates a Claim of
PATCH /api/v3/bootenvs/fredthat wants to update OS.Name and OS.IsoName creates a Claim of
- The token is checked to make sure it is still valid based on the system Secret, the user Secret, and the grantor Secret. If any of these have changed, or the token has expired, the API will return a 403.
- The list of created Claims is tested to see if it is contained by any one of the Roles contained in the Token, or by any direct Claims contained in the Token. If all of the created Claims are satisfied, the request is considered to be authorized, otherwise the API will return a 403.
- The API carries out the request and returns an appropriate response.