io7m | single-page | multi-page | epub | Idstore User Manual 1.0.0-beta0004
3. Configuration
Previous
Front Matter
Up
5. Command-Line Interface
Next

# 4. Model

- 4.1. Overview
- 4.2. Users/Administrators
  - 4.2.1. Separation
  - 4.2.2. Identifiers
  - 4.2.3. Names
  - 4.2.4. Email Addresses
  - 4.2.5. Permissions
  - 4.2.6. Initial Administrator
- 4.3. Permissions
- 4.4. Audit Log
- 4.5. User View
- 4.6. User API
- 4.7. Admin API

## 4.1. Overview

1
The idstore server is primarily intended to act as a single-source-of-truth for the identities of users within arbitrary sets of decoupled services. It acts as a secure store for login credentials for users, and is intended to relieve server application authors of the burden of having to constantly reimplement login processes, credential stores, password reset workflows, and other miscellanea related to authentication.
2
This section of the documentation describes the internal idstore model.

## 4.2. Users/Administrators

## 4.2.1. Separation

1
The idstore package contains two types of user accounts: users and administrators. A user is an unprivileged account that is permitted to log in to the server only via the user view, and/or the user API. An administrator is an account that is permitted to log in to the server only via the admin API, and is permitted to perform administrative actions (subject to permissions checks) such as creating user accounts, reading the audit log, etc.

## 4.2.2. Identifiers

1
User and administrator accounts have immutable, unique identifiers represented by RFC 4122 UUID values. Identifiers are not secret and may be freely shared between systems.

## 4.2.3. Names

1
User and administrator accounts have names that are used for login operations. Names must match the regular expression \p{LC}[\p{LC}\p{N}_-]{0,255}. Names must be unique within a given idstore server, but can be changed at the user/administrator's discretion at any time.

## 4.2.4. Email Addresses

1
User and administrator accounts must have at least one unique (within a given idstore server) email address associated with them. Email addresses can be added and removed at any time, but it is not permitted for the number of addresses on an account to be less than one.

## 4.2.5. Permissions

1
Each administrator account has a set of permissions associated with it. When the administrator account attempts to perform an operation on the server, the account's permissions are checked to see if it has all the permissions required to perform the action.
2
An administrator account holding the ADMIN_WRITE_PERMISSIONS permission may grant any permissions it holds to another administrator account. Similarly, An administrator account holding the ADMIN_WRITE_PERMISSIONS permission may revoke any permissions it holds from another administrator account.

## 4.2.6. Initial Administrator

1
The initial administrator is a designated adminstrator account that always has all of the available permissions. For security reasons, this account should have an extremely strong password, and should only be used to perform the necessary initial configuration of the server; it is analogous to the UNIX root account.

## 4.3. Permissions

1
The following administrator permissions are available:

### 4.3.2. Permissions

Permission | Description
--- | ---
ADMIN_DELETE | The bearer of this permission is permitted to delete administrator accounts.
ADMIN_CREATE | The bearer of this permission is permitted to create new administrator accounts.
USER_BAN | The bearer of this permission is permitted to ban users.
ADMIN_BAN | The bearer of this permission is permitted to ban administrators.
ADMIN_WRITE_CREDENTIALS | The bearer of this permission is permitted to modify the credentials of administrators.
ADMIN_WRITE_CREDENTIALS_SELF | The bearer of this permission is permitted to modify its own credentials.
ADMIN_WRITE_EMAIL | The bearer of this permission is permitted to modify the email addresses of administrators.
ADMIN_WRITE_EMAIL_SELF | The bearer of this permission is permitted to modify its own email addresses.
ADMIN_WRITE_PERMISSIONS | The bearer of this permission is permitted to modify the permissions of administrators.
ADMIN_WRITE_PERMISSIONS_SELF | The bearer of this permission is permitted to modify its own permissions.
ADMIN_READ | The bearer of this permission is permitted to read the accounts of administrators.
AUDIT_READ | The bearer of this permission is permitted to read the audit log.
USER_DELETE | The bearer of this permission is permitted to delete user accounts.
USER_CREATE | The bearer of this permission is permitted to create new user accounts.
USER_WRITE_CREDENTIALS | The bearer of this permission is permitted to modify the credentials of existing user accounts.
USER_WRITE_EMAIL | The bearer of this permission is permitted to modify the email addresses existing user accounts.
USER_READ | The bearer of this permission is permitted to read existing user accounts.

## 4.4. Audit Log

1
The server maintains an append-only audit log consisting of a series of audit events. An audit event has an integer id, an owner (represented by an account UUID), a timestamp, a type, and a message.

### 4.4.2. Audit Log

## 4.5. User View

1
The user view is the web interface exposed to users. It offers the ability for users to see their own account information, and also to handle the email-based password reset workflow.

### 4.5.2. Web Interface

## 4.6. User API

1
The user API is the interface exposed to user clients. It exposes a Cedarbridge-based API over HTTP, using the included schema.
2
The user API is largely intended to be used by other servers that want to use an idstore server to handle authentication.

## 4.7. Admin API

1
The admin API is the interface exposed to administrators. Like the user API, it exposes a Cedarbridge-based API over HTTP, using the included schema. It is the service used by the included admin shell, and by projects such as idstore_gui.
3. Configuration
Previous
Front Matter
Up
5. Command-Line Interface
Next
io7m | single-page | multi-page | epub | Idstore User Manual 1.0.0-beta0004