Users, roles and access
A person signs in to the console with a local account or with their Active Directory account. What they may do is decided by their roles, each given in one environment or in all of them. All of this is managed under Users & access, which has four tabs: Users, Service accounts, Roles and Directory.
Who may open it
Users & access belongs to the Platform administrator, and the menu shows it to no one else. Its tabs need the platform permissions to manage users (users.manage), service accounts (service_accounts.manage), roles (roles.manage) and the directory connection (identity.manage). Only the Platform administrator holds platform permissions.
The built-in roles
| Role | Scope | What it may do |
|---|---|---|
| Platform administrator | The whole installation | Everything, in every environment: the environments and their connections, users, roles, the directory connection and the platform audit log. |
| Environment administrator | One environment | Everything in that environment, including secrets, the request records, Analytics, Alerts and the audit log. |
| Editor | One environment | Create and change routes, services, upstreams, consumers with their credentials, consumer groups, global rules, plugin configs, the Environment-wide settings of plugins, protos and stream routes. View certificates and secrets without changing them, with their secret values masked. No audit log, request records, Analytics or Alerts. |
| Viewer | One environment | View what an Editor views, change nothing. Read-only pages say so, and the Raw JSON editor is locked. |
An environment's own record belongs to the Platform administrator: its name, the address and key of its Admin API, its gateway address and the addresses of its stores. See Environment settings. The Editor changes something else, the Environment-wide settings of plugins, which apply a plugin's settings to the whole environment.
Built-in roles are fixed. You can add custom roles that apply within an environment. A custom role names, for each kind of object, whether it may view or manage; manage includes view. Custom roles cannot be deleted while they are assigned to someone.
How a person gets a role
A role is given as an assignment: a role plus an environment, or All environments, which also covers environments added later. A platform role covers every environment on its own and takes no environment.
A person with no role in an environment sees it in the switcher with a lock and cannot open it. Everyone sees the list of environments.
A local user
On the Users tab, select New user. Fill in the Username, pick a Role and an Environment, and set a password. For a platform role the environment field is absent. Select Create user. The password you set is temporary: the person has to change it at their first sign-in. Passwords are at least 12 characters long.
Through Active Directory
A person can also get a role through a directory group, or be added from the directory one by one before their group is mapped. They sign in on the same form with their domain account, and their page says whether each role came directly or by group. Connect Active Directory describes the connection, the mappings and what the server does with the directory.
Service accounts
Scripts and CI pipelines call the API with a token instead of a person's session. A service account carries environment roles only. Each account can hold up to 5 active tokens, each valid for 30, 90 or 180 days or for a year. A token is shown once, when it is created, and is sent as a bearer token in the Authorization header. Tokens in URLs are rejected. A token can be revoked, and deleting the account stops every token. Service accounts and the API describes them in full.
Sessions and passwords
- A session ends after an hour without activity and after 12 hours in any case. Both are settings of the server,
G8_SESSION_IDLEandG8_SESSION_MAX. - After 10 failed sign-ins within 15 minutes, the account is locked for 15 minutes. The lock lifts on its own, for the only Platform administrator too. Sign-ins are limited to 20 a minute from one address.
- Changing your own password signs out your other sessions. Sign out everywhere in the user menu ends every other session of yours, on every browser and device; this one stays signed in. An administrator can do the same for another user from the user's page.
- The first administrator is created in the console after the server's first start, with the setup token the server prints in its log.
Reset a password, disable a user
A local user who forgot their password asks a Platform administrator. On the user's page, the administrator selects Reset password, and the dialog says: A new temporary password is generated and shown once. Every session of the user ends now. The person signs in with it and has to change it. A directory user's password lives in the directory and is not reset here.
Disable on the user's page ends the person's sessions, and a disabled user cannot sign in until Enable is selected. Their roles stay with them.
The server keeps at least one active Platform administrator. The last one cannot be disabled, deleted or lose the role, and an administrator cannot disable or remove their own access. Only a Platform administrator resets passwords, and the server has no reset of its own, so nothing brings back the only Platform administrator's password once it is forgotten. Give the role to a second person before that case.
What a Viewer sees
A Viewer sees the Gateway section of the menu with its routes, services, upstreams, consumers, certificates and plugins, and the tabs under them. Those tabs hold stream routes, protos, consumer groups, global rules, plugin configs and secrets, and a Viewer can open each of them. There is no button to create or change anything, read-only pages say so, and the Raw JSON editor is locked. A key, a password or a certificate's private key stays masked, with no button to reveal it. The Observe section is absent from the menu. Opening the audit log, Traffic Explorer, Analytics or Alerts by address shows a page that says which role the person has and who may open it.
Related
- Environments: what a role in one environment covers and what stays separate.
- Custom roles: the permissions each role holds, and making a role of your own.
- Audit log: sign-ins, directory changes and every change a user makes are recorded there.