gRPC: identity

Identity: login, sessions, roles, permissions.

`IdentityService`

Sign-in, sessions, roles and permissions.

Method	Request	Response	Description
`Login`	`LoginRequest`	`LoginResponse`	Signs in with a user name and password; may ask for a second factor.
`CompleteMfa`	`CompleteMfaRequest`	`SessionInfo`	Completes a sign-in with the second factor.
`Logout`	`Empty`	`Empty`	Ends the caller's session.
`WhoAmI`	`Empty`	`WhoAmIResponse`	The caller's user, groups and session.
`ListRoles`	`Empty`	`ListRolesResponse`	Every role with its privileges.
`ListPermissions`	`ListPermissionsRequest`	`ListPermissionsResponse`	Permissions of an object.
`SetPermission`	`SetPermissionRequest`	`Permission`	Assigns a role to a user or group on an object.
`RemovePermission`	`RemovePermissionRequest`	`Empty`	Removes a permission from an object.
`CheckPrivilege`	`CheckPrivilegeRequest`	`CheckPrivilegeResponse`	Whether the caller holds `privilege` on `entity`.

Messages

`LoginRequest`

Password login.

Field	Number	Type	Description
`username`	1	`string`	User name.
`password`	2	`string`	Password.
`kind`	3	`SessionKind`	Kind of session to open.

`UserView`

A user account.

Field	Number	Type	Description
`username`	1	`string`	User name.
`display_name`	2	`string`	Name to show.
`email`	3	`string`	Email address.
`enabled`	4	`bool`	The account may sign in.
`groups`	5	repeated `string`	Groups the user belongs to.
`mfa_enrolled`	6	`bool`	Two-step verification is set up.
`break_glass`	7	`bool`	Break-glass account for emergency access.
`password_rotation_required`	8	`bool`	The password must be changed at the next sign-in.

`SessionInfo`

An open session.

Field	Number	Type	Description
`token`	1	`string`	Bearer token; shown once.
`session_id`	2	`string`	Id of the session; the bearer token of later calls.
`expires_at`	3	`string`	End of the session, RFC 3339.
`user`	4	`UserView`	The signed-in user.
`password_rotation_required`	5	`bool`	The session is restricted until the password is changed.
`mfa_enrolment_required`	6	`bool`	The session may only reach MFA self-service until enrolment completes.

`MfaChallenge`

The login needs a second factor.

Field	Number	Type	Description
`pending_token`	1	`string`	Token to send with the code to `CompleteMfa`.

`LoginResponse`

A session, or a challenge for the second factor.

Field	Number	Type	Description
`session`	1	`SessionInfo`	The open session.
`mfa_required`	2	`MfaChallenge`	The second factor is needed first.

`CompleteMfaRequest`

The second factor of a login.

Field	Number	Type	Description
`pending_token`	1	`string`	Token of the challenge.
`code`	2	`string`	Six-digit code or a recovery code.

`WhoAmIResponse`

The caller and its session.

Field	Number	Type	Description
`username`	1	`string`	User name.
`groups`	2	repeated `string`	Groups of the user.
`session_id`	3	`string`	Id of the session.
`kind`	4	`SessionKind`	Kind of session.
`mfa_pending`	5	`bool`	The session waits for the second factor.
`password_rotation_required`	6	`bool`	The password must be changed before anything else works.
`break_glass`	7	`bool`	The session belongs to a break-glass account.

`Role`

A role.

Field	Number	Type	Description
`id`	1	`string`	Id of the role.
`name`	2	`string`	Name.
`description`	3	`string`	What the role is for.
`privileges`	4	repeated `string`	Privilege ids the role holds.
`system`	5	`bool`	Built-in role, not editable.

`ListRolesResponse`

The roles.

Field	Number	Type	Description
`items`	1	repeated `Role`	Every role.

`Principal`

A user or a group.

Field	Number	Type	Description
`type`	1	`Principal.Type`	User or group.
`name`	2	`string`	User name or group name.

`Permission`

A role granted to a principal on an object.

Field	Number	Type	Description
`id`	1	`string`	Id of the permission.
`entity`	2	`string`	Id of the object.
`principal`	3	`Principal`	Who gets the role.
`role`	4	`string`	Id of the role.
`propagate`	5	`bool`	The permission also applies to the objects below.

`ListPermissionsRequest`

Lists permissions.

Field	Number	Type	Description
`entity`	1	`string`	Id of the object.

`ListPermissionsResponse`

The permissions.

Field	Number	Type	Description
`items`	1	repeated `Permission`	Permissions of the object.

`SetPermissionRequest`

Grants a role on an object.

Field	Number	Type	Description
`entity`	1	`string`	Id of the object.
`principal`	2	`Principal`	Who gets the role.
`role`	3	`string`	Id of the role.
`propagate`	4	`bool`	Also apply to the objects below.

`RemovePermissionRequest`

Removes a permission.

Field	Number	Type	Description
`id`	1	`string`	Id of the permission.

`CheckPrivilegeRequest`

Asks whether the caller holds a privilege.

Field	Number	Type	Description
`entity`	1	`string`	Id of the object.
`privilege`	2	`string`	Privilege id.

`CheckPrivilegeResponse`

Answer of a privilege check.

Field	Number	Type	Description
`granted`	1	`bool`	The caller holds the privilege on the object.

Enums

`SessionKind`

Kind of session a login opens.

Value	Number	Description
`SESSION_KIND_INTERACTIVE`	0
`SESSION_KIND_API`	1

`Principal.Type`

Kind of principal.

Value	Number	Description
`TYPE_USER`	0
`TYPE_GROUP`	1