Factors
Last updated
Last updated
Factors (authentication methods) offer the option to securely prove ownership of an account - whether the account is a user or application (client). Their use is mandatory as they sit at the very heart of what Quasr offers. Each factor is designed with security, privacy and user experience as crucial requirements.
Before we start let's tackle an important terminology:
Factor - When we refer to a factor we generally refer to a factor configuration and not to a specific instance itself. For example the configuration of a username factor. Sometimes we do use the term as well for a specific instantiation.
Enrollment - When we refer to an enrollment we refer to an individual instance of a factor. For example a specific username or password. We always use this term to refer a specific instance.
Please note that enrollments have immutable data, i.e. you can't change the data of an enrollment after it's been created (for example a username or password). If you like to update the enrollment you must:
Create a new enrollment with the updated value.
Disable or delete the old enrollment with the previous value (if desired).
The philosophy behind this approach is as follows:
An enabled enrollment resembles a valid/active authentication method. You can have multiple enabled enrollments for the same user and factor indicating all are (still) valid/active.
A disabled enrollment resembles a currently invalid/inactive method but one that was historically valid.
Hence the following approach is recommended:
If you update the enrollment because of a change, or you need to be able to recover the old enrollment, then keep the old enrollment but disable it.
If you update the enrollment because of a correction, and you don't need to be able to recover the old enrollment, then delete the old enrollment.
Please note that the data of an enrollment is stored securely hashed (default) or encrypted (exceptional) and never logged. Hence for most enrollments you won't be able to extract the clear data and if you delete the enrollment you won't be able to recover the data.
Quasr supports various types of factors:
email (which gives the option to use a default built-in email provider without need for extension)
Private Key - This allows users or clients to authenticate using a private/public key pair (asymmetric secret). Users must prove ownership of the private key by signing a JWT, constructed as a OAuth 2.0 assertion. This follows the Private Key JWT authentication standard for OAuth 2.0 clients.
Hosted Key Set - This allows users or clients to authenticate using a private/public key pair but here the public key(s) are made available over a publicly-accessible URL, following the JWKS standard. In this case users/clients must setup and provide the URL themselves. This also follows the Private Key JWT authentication standard for OAuth 2.0 clients.
Personal Token - This allows users to authenticate using a server-signed token (JWT). The token can be used multiple times but has a fixed expiration date.
Microsoft
Discord
Quasr
For each factor you can specify the following:
Score - Each factor will have a score indicating what (security) score a user gains when successfully passing the factor using the Authentication API during signup or login. This allows reflecting security by individual factors as well as multi-factor / step-up authentication (MFA) by passing more factors.
Internal - This indicates that the factor must only be used by internal accounts. For example, a login with Microsoft using the corporate IDP.
Restricted - This indicates the the factor can only be created by the system or an admin. Hence not allowing accounts to create their own. For example an email username but after the email has been verified.
Regex - This is only relevant for secret and OTP factors and is a regular expression (RegEx) to which any input must comply. Once set you can't change the regex.
Unique - This indicates whether each enrollment for the factor must be unique. So if for example the username factor is unique than only 1 account can have a specific username.
Case Sensitive - This indicates whether input must be considered case sensitive.
Require Validation for Enablement - This indicates whether any enrollment must first be validated before it gets enabled. For some factors this will be mandatory as intrinsic to its working, for others this will be optional. Please note that some validation could also be done in the frontend like asking for the password twice to avoid typos.
- This allows users or clients to authenticate using a symmetric secret. This follows the Client Secret authentication standard for OAuth 2.0 clients.
- This allows users to authenticate using a string. Under the hood this is implemented as a secret factor with the nuance a username is a more publicly known "secret". Hence usernames are stored hashed which improves security and privacy as often usernames contain personal data. The following usernames are supported out-of-the-box:
- The allows users to authenticate using a password. Under the hood this is implemented as a secret factor with the nuance a password is a more privately known "secret".
- This allows users to authenticate using a short-lived password, which can only be used once and is delivered to the user over some channel (email, text, chat, phone, etc.). Note that OTPs are delivered using an extension. Following channels are supported out-of-the-box:
- This allows users to authenticate using a short-lived code/password as generated by an authenticator app of their own liking. As long as the authenticator app supports the OATH standard with a time-based OTP (TOTP) it's compatible.
- This allows users to authenticate using an existing Identity Provider (IDP) which supports either OpenID Connect 1.0 (OIDC) or OAuth 2.0 with a claims-providing API (similar to UserInfo endpoint with OIDC). Besides a generic factor following identity providers are supported out-of-the-box:
