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.
This section of the documentation describes the internal idstore model.
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.
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.
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
and must be unique within a given
idstore server, but can be changed at the
user/administrator's discretion at any time.
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.
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.
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.
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.
The following administrator permissions are available:
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.
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.
The
user API is the interface exposed to user clients. It exposes
a
Cedarbridge-based API over HTTP,
using the included
schema.
The user API is largely intended to be used by other servers that want to use an
idstore
server to handle authentication.
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.
There are a number of situations where the idstore server uses an external MTA.
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.
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.
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.
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.
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.
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.
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.
Maintenance mode is not a persistent setting; if the server is restarted, it will start up
in the normal non-maintenance mode.