Skip to content

docs: MFA default-on, per-method meta fields, user search by ID, org member email #75

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
lakhansamani wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: MFA default-on, per-method meta fields, user search by ID, org member email #75

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 24 additions & 6 deletions docs/core/graphql-api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -99,6 +99,10 @@ It returns `Meta` type with the following possible values
| `is_basic_authentication_enabled` | It gives information, if basic auth is enabled or not |
| `is_magic_link_login_enabled` | It gives information if password less login is enabled or not |
| `is_sign_up_enabled` | It gives information if sign up is enabled or not |
| `is_totp_mfa_enabled` | Whether TOTP MFA enrollment and login are available |
| `is_email_otp_mfa_enabled` | Whether email OTP MFA enrollment and login are available (requires SMTP configured) |
| `is_sms_otp_mfa_enabled` | Whether SMS OTP MFA enrollment and login are available (requires Twilio configured) |
| `is_webauthn_enabled` | Whether WebAuthn/passkey enrollment is available |

**Sample Query**

Expand All @@ -114,6 +118,10 @@ query {
is_basic_authentication_enabled
is_magic_link_login_enabled
is_sign_up_enabled
is_totp_mfa_enabled
is_email_otp_mfa_enabled
is_sms_otp_mfa_enabled
is_webauthn_enabled
}
}
```
Expand Down Expand Up @@ -952,7 +960,13 @@ query {

#### `_admin_meta`

Query to get admin metadata (server info available to admins).
Query to get admin metadata (server info available to admins). Returns all fields from `meta` plus admin-only fields.

**Admin-only fields**

| Key | Description |
| ----------------------------------- | ---------------------------------------------------------- |
| `is_multi_factor_auth_service_enabled` | Whether at least one MFA method is available (at least one method enabled and its provider configured) |

**Sample Query**

Expand All @@ -961,6 +975,10 @@ query {
_admin_meta {
version
client_id
is_totp_mfa_enabled
is_email_otp_mfa_enabled
is_sms_otp_mfa_enabled
is_multi_factor_auth_service_enabled
}
}
```
Expand All @@ -979,14 +997,14 @@ Query to get all the `_users`. This query is only allowed for super admins. It r
}
```

It can take optional `params` input of type `PaginatedInput` with following keys
It can take optional `params` input of type `ListUsersRequest` with following keys

**Request Params**

| Key | Description | Required | Default |
| ------- | ---------------------------- | -------- | ------- |
| `page` | Number of page that you want | false | 1 |
| `limit` | Number of rows that you want | false | 10 |
| Key | Description | Required | Default |
| ------------ | ------------------------------------------------------------------------------------- | -------- | ------- |
| `pagination` | Object with `page` and `limit` for pagination | false | page: 1, limit: 10 |
| `query` | Case-insensitive substring filter (matches against user ID, email, given_name, family_name, nickname). Empty or absent means no filter. | false | empty |

**Sample Query**

Expand Down
3 changes: 2 additions & 1 deletion docs/core/rest-api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -431,13 +431,14 @@ Get admin-level metadata about the server (version, feature flags).

#### `POST /v1/admin/users`

List all users with pagination.
List all users with pagination and optional search.

**Request body**

| Field | Type | Description | Required |
| ------------ | ------------------- | ------------ | -------- |
| `pagination` | `{ page, limit }` | Page & limit. | no |
| `query` | `string` | Case-insensitive substring filter (matches against user ID, email, given_name, family_name, nickname). | no |

**Response** `{ users: User[], pagination: { page, limit, total, offset } }`

Expand Down
24 changes: 20 additions & 4 deletions docs/core/server-config.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -123,15 +123,31 @@ Organization / UI:
--enable-basic-authentication=true \
--enable-email-verification=true \
--enable-magic-link-login=true \
--enable-signup=true \
--enable-totp-login=true \
--enable-email-otp=true \
--enable-sms-otp=false
--enable-signup=true
```

These replace v1 flags such as `DISABLE_BASIC_AUTHENTICATION`, `DISABLE_EMAIL_VERIFICATION`, etc.
See the [Auth behavior mapping](../migration/v1-to-v2#auth-behavior) for exact correspondences.

### Multi-factor authentication (MFA)

```bash
./authorizer \
--disable-totp-login=false \
--disable-email-otp=false \
--disable-sms-otp=false \
--enforce-mfa=false
```

MFA is **enabled by default** in v2. The following flags allow you to disable specific methods:

- **`--disable-totp-login`** (default `false`): set to `true` to disable TOTP (time-based one-time password) MFA enrollment and login.
- **`--disable-email-otp`** (default `false`): set to `true` to disable email OTP enrollment. Email OTP is only available when SMTP is configured (see [SMTP](#smtp)).
- **`--disable-sms-otp`** (default `false`): set to `true` to disable SMS OTP enrollment. SMS OTP is only available when Twilio is configured (see [Twilio](#twilio-sms-otp)).
- **`--enforce-mfa`** (default `false`): set to `true` to make MFA mandatory — all users must enroll in at least one MFA method during signup and cannot skip it. When `false`, MFA enrollment is optional.

MFA is considered "available" when at least one method is enabled and its provider (SMTP for email, Twilio for SMS) is configured. The public `meta` query exposes which methods are available via `is_totp_mfa_enabled`, `is_email_otp_mfa_enabled`, and `is_sms_otp_mfa_enabled` fields, allowing the login UI to conditionally show MFA enrollment prompts.

### Cookies

```bash
Expand Down
20 changes: 19 additions & 1 deletion docs/enterprise/organizations.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -75,11 +75,29 @@ mutation {
query {
_org_members(params: { org_id: "ORG_ID" }) {
pagination { total }
org_members { user_id roles created_at }
org_members {
user_id
roles
created_at
email
given_name
family_name
}
}
}
```

**Organization member fields**

| Field | Type | Description |
| ------------ | -------- | ----------- |
| `user_id` | `string` | The user's unique identifier |
| `roles` | `[string]` | Per-organization roles assigned to this member |
| `created_at` | `string` | Timestamp when the membership was created |
| `email` | `string` | User's email (may be empty if the user no longer exists) |
| `given_name` | `string` | User's first name (may be empty if the user no longer exists) |
| `family_name` | `string` | User's last name (may be empty if the user no longer exists) |

```graphql
mutation {
_remove_org_member(params: { org_id: "ORG_ID", user_id: "USER_ID" }) {
Expand Down
19 changes: 17 additions & 2 deletions docs/migration/v1-to-v2.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -272,9 +272,9 @@ Use these v2 **CLI flags** instead of v1 env or dashboard config. Flag names use
| `DISABLE_BASIC_AUTHENTICATION` | `--enable-basic-authentication` (inverted) |
| `DISABLE_EMAIL_VERIFICATION` | `--enable-email-verification` (inverted) |
| `DISABLE_MAGIC_LINK_LOGIN` | `--enable-magic-link-login` (inverted) |
| `ENFORCE_MULTI_FACTOR_AUTHENTICATION` | `--enforce-mfa`, `--enable-mfa` |
| `ENFORCE_MULTI_FACTOR_AUTHENTICATION` | `--enforce-mfa` |
| `DISABLE_SIGN_UP` | `--enable-signup` (inverted) |
| TOTP / OTP | `--enable-totp-login`, `--enable-email-otp`, `--enable-sms-otp` |
| TOTP / OTP (all enabled by default in v2) | `--disable-totp-login`, `--disable-email-otp`, `--disable-sms-otp` (use to opt-out) |
| Mobile basic auth | `--enable-mobile-basic-authentication` |
| Phone verification | `--enable-phone-verification` |

Expand Down Expand Up @@ -405,6 +405,21 @@ its first burst:
See the new [Security Hardening](../core/security#trusted-proxies) page
for the full topology table and flag reference.

#### MFA flags reversed: `--enable-*` removed, `--disable-*` added

MFA is now **enabled by default** and **optional per user** (unless `--enforce-mfa=true`). The v1 pattern of opt-in flags has been inverted:

| v1 | v2 |
|----|----|
| `--enable-totp-login=true` | `--disable-totp-login=false` (default) |
| `--enable-email-otp=true` | `--disable-email-otp=false` (default) |
| `--enable-sms-otp=true` | `--disable-sms-otp=false` (default) |
| `--enable-mfa` (no longer used) | Use `--enforce-mfa` if you need to make MFA mandatory |

**Action required:** if your v1 config had `--enable-totp-login=false` or `--enable-email-otp=false`, translate them to `--disable-totp-login=true` or `--disable-email-otp=true` in v2. The old `--enable-mfa` flag is removed; do not use it.

The new `--disable-totp-login`, `--disable-email-otp`, and `--disable-sms-otp` flags default to `false` (meaning the methods are enabled), and MFA is only "available" when at least one method is enabled and its provider (SMTP, Twilio) is configured.

### Database schema: `email` / `phone_number` are no longer `UNIQUE`

In v1 the `email` and `phone_number` columns of the `authorizer_users` and
Expand Down