API Definition of User Service V3

[hifabienne]

We want to give our customers the possibility to define their own user schemas and create users according to those schemas. To avoid breaking changes on our current user service, we will introduce the version v3 and provider a migration path later on.

To get an impression of what the service is capable of and how this looks like in the future, we want to start with the API definition, which also gives us the possibility to collect feedback in an early state.

Acceptance Criteria

• API is behind a feature flag and marked as Alpha? Or not ready. -> only proto definition as of now
• API is defined in a new User Service V3 with proto definitions
• All requests and methods are documented with examples
• User Schema Requests:
  • ListUserSchemas: lists latests states schemas
  • UserSchemaByID: shows details of a specific schema
  • CreateUserSchema: adds a new schema
  • UpdateUserSchema: changes an existing schema.
  • DeactivateUserSchema: moves the schema to a read only state. Users of this schema cannot be updated anymore. Users are still able to log in
  • ReactivateUserSchema: moves the schema state to active
  • DeleteUserSchema: Removes an exisiting schema. This operation is only allowed if there are no associated users
  • ValidateUser: Verifies if the user satisfies a schema -> added to user service
• User Request:
  • ListUsers: lists users
  • UserByID: shows details of a specific user
  • CreateUser: adds a new user
  • UpdateUser: changes an existing user. The type of a user cannot be changed
  • DeleteUser: Removes an exisiting user.
  • AddAuthenticator: Adds an authenticator
  • RemoveAuthenticator: Removes an existing atuehticator
  • LockUser: changes the state of the user to locked
  • UnlockUser: changes the state of the user to active after it was locked
  • DeactivateUser: changes the state of the user to inactive
  • ReactivateUser: changes the state of the user to active after it was locked

Open Questions

• How to handle the permissions? admin/user? Something relating to the permissions we already have internally?

Additional Information

User Object

• id: unchangeble, unique identifier of the system
• schema:
  • type: schema type of the user (e.g. human/machine)
  • revision: read only, revision of the schema the user was stored the last time (e.g. 4)
• authenticators: list of possibilites how a user can authenticate itself. there can be multiple authenticators of the same type
• contact: email and phone of the user if provided
• state: one of Active, Inactive, Locked, Deleted
• data/profile/traits: custom fields of a user based on the type (whats the best name for this?)

Authenticators

• username: human readable identifier of the user
  • username
  • isOrgSpecific: if set to true, login with this authenticator is only possible if org is defined TODO: add to LoginPolicy (Authenticator list as proposal)
• password
• webAuthNKey
• one time password
  • email
  • phone
• time based one time password
• jwt profile key
• identity provider
  • identity provider
  • isOrgSpecific: if set to true, login with this authenticator is only possible if org is defined TODO: add to LoginPolicy (Authenticator list as proposal)
• FUTURE: recovery code

User Schema

• id: read only unique identifier
• state: state of the schema
• type: single word which describes the schema
• revision: read only version of the schema, each update increases the revision
• schema: describes the user
• possibleAuthenticators: defines the possible types of authenticators. this allows creating different user types like human/machine without usage of actions to validate possible authenticators. Removal of an authenticator does not remove the authenticator on a user
  • TODO: move user.isOrgSpecific to here (on username and idp)

permissions

permission

Following permissions are allowed r (4), w (2), rw (6)

• admin: defines the permissions of the admin
• user: defines the user of the user

oidcClaim / samlMapping

It is needed to define the oidc Claim and saml mapping so ZITADEL knows how to map the user infromations to the oidc / saml responses/tokens

additional formats

• phone: possibility to add declare phone numbers
• language: language tag analog to ietf bcp 47

[hifabienne]

@stebenz @eliobischof Can you please estimate this issue?

[stebenz]

Technical estimation:

• service definition: 1d
• proto message definition: 2d
• permission checks definition: 1d
• examples: 1d
• documentation in proto: 1d