io7m | single-page | multi-page | epub | Idstore User Manual 1.2.1
3. Configuration
Previous
Front Matter
Up
5. Monitoring
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.8. Mail
  - 4.8.1. Overview
  - 4.8.2. Password Reset
  - 4.8.3. Email Additions
  - 4.8.4. Email Removals
- 4.9. Maintenance Mode

## 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 are case-insensitive [1] and 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.
MAIL_TEST | The bearer of this permission is permitted to send test emails.

## 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.

## 4.8. Mail

## 4.8.1. Overview

1
There are a number of situations where the idstore server uses an external MTA.

## 4.8.2. Password Reset

1
If a user forgets their password, they can request a password reset token. The server will generate a strong random token t with a configurable expiration date. For each email address e associated with the user's account, the server will email t to e. The user can retrieve t from one of their email accounts and recite t back to the server to have their password reset.

## 4.8.3. Email Additions

1
If a user wants to add a new email address f to their account, they can request email addition tokens. The server will generate a pair of strong random tokens tpermit and tdeny, each with a configurable expiration date. For each email account e associated with the user's account, the server will email tdeny to e. The server will email tpermit to f. Assuming the user really does have access to f, they can read the resulting email and recite tpermit back to the idstore server to have the new address added to their account.
2
In the event that the user's account is compromised, and a hostile party is attempting to add a new email address to the user's account, the user can recite tdeny back to the server from any of their other email accounts in order to deny the address addition. This potentially alerts users to the fact that their account has been compromised, and allows them to mitigate the damage if they act fast enough.

## 4.8.4. Email Removals

1
If a user wants to remove an existing email address f from their account, they can request email removal tokens. The server will generate a pair of strong random tokens tpermit and tdeny, each with a configurable expiration date. For each email account e associated with the user's account (where e != f), the server will email tdeny to e. The server will email tpermit to f. Assuming the user really does have access to f, they can read the resulting email and recite tpermit back to the idstore server to have the address removed from their account.
2
In the event that the user's account is compromised, and a hostile party is attempting to remove the user's existing email address from the compromised account, the user can recite tdeny back to the server from any of their other email accounts in order to deny the address removal. This potentially alerts users to the fact that their account has been compromised, and allows them to mitigate the damage if they act fast enough.
3
If the user no longer has access to f, they cannot remove it. In this case, an administrator will need to remove the address manually.

## 4.9. Maintenance Mode

1
When performing essential maintenance such as a database upgrade, the server can be placed into maintenance mode. In this mode, all requests made to the user API or user view will return a 503 HTTP status code and a configurable message.

### 4.9.2. Maintenance Mode

3
Maintenance mode is not a persistent setting; if the server is restarted, it will start up in the normal non-maintenance mode.

## Footnotes

1 | Names are case-insensitive in order to make it slightly more difficult for a hostile user to impersonate another by picking a name that only varies with case. References to this footnote: 1

3. Configuration
Previous
Front Matter
Up
5. Monitoring
Next
io7m | single-page | multi-page | epub | Idstore User Manual 1.2.1