Skip to content

docs: describe v0.23 as released across the guides and comparisons #170

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

Draft
Bccorb wants to merge 1 commit into
base: docs/v0.23-release-notes
Choose a base branch
from
+64 −76
Draft

docs: describe v0.23 as released across the guides and comparisons #170

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
27 changes: 13 additions & 14 deletions src/content/docs/build/login-hooks-custom-claims.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,11 +21,10 @@ There are two tools, and most apps need only the second:
Hook calls are signed the same way as [webhooks](/build/webhooks), so your hook service can prove a
call came from your Seamless Auth instance.

<Aside type="caution" title="Needs auth API v0.23.0, not released yet">
Login hooks, custom claims and every route on this page need `seamless-auth-api` v0.23.0. The
latest release is v0.22.0, which has none of them. The console's **Login hooks** and **Custom
claims** pages and the CLI's `seamless hooks` and `seamless claims` commands are not released yet,
and neither are custom claims in OpenID Provider tokens (see [Versions](#versions)).
<Aside type="note" title="Needs auth API v0.23.0">
Login hooks, custom claims and every route on this page need `seamless-auth-api` v0.23.0 or later.
Custom claims in OpenID Provider tokens also need the provider at 0.4.0 (see
[Versions](#versions)).
</Aside>

---
Expand Down Expand Up @@ -180,9 +179,9 @@ only in production, never the API's own host, and link-local addresses never.

**Console:** the **Login hooks** page (`/login-hooks` in `seamless-auth-admin-dashboard`) has one
section per trigger with the URL, timeout, failure mode, a test call, secret rotation and the
invocation log. It is not in a console release yet (seamless-auth-admin-dashboard#343).
invocation log. It is in the console from v0.14.0.

**CLI:** not in a CLI release yet (seamless-cli#359). With it:
**CLI:** `seamless-cli` 0.30.0 and later:

```bash
seamless hooks set post_login --url https://hooks.example.com/seamless # prints the secret once
Expand Down Expand Up @@ -340,10 +339,10 @@ both set, whatever order the roles were granted in.

**Console:** the **Custom claims** page (`/custom-claims` in `seamless-auth-admin-dashboard`)
edits each source's set as JSON, shows the reserved names and the budget the API reports, and
refuses a reserved name, nesting past depth 3 or an oversized set before step-up. It is not in a
console release yet (seamless-auth-admin-dashboard#343).
refuses a reserved name, nesting past depth 3 or an oversized set before step-up. It is in the
console from v0.14.0.

**CLI:** not in a CLI release yet (seamless-cli#359). `claims set` replaces the whole set and asks
**CLI:** `seamless-cli` 0.30.0 and later. `claims set` replaces the whole set and asks
before removing a claim:

```bash
Expand Down Expand Up @@ -562,11 +561,11 @@ reads `plan` from the access token instead of `https://example.com/plan`.

| Component | First version | Status |
| --------------------------------- | ----------------------------- | ------ |
| `seamless-auth-api` | v0.23.0 | Not released. v0.22.0 is the latest |
| `seamless-auth-api` | v0.23.0 | Released |
| `@seamless-auth/types` | 0.39.0 | Published |
| OpenID Provider (`permissions` and `custom_claims` scopes) | The release with seamless-auth-oidc-provider#63 | Not released |
| `seamless-auth-admin-dashboard` | The release after v0.13.0 (Login hooks and Custom claims pages) | Not released (seamless-auth-admin-dashboard#343) |
| `seamless-cli` | The release after 0.29.0 (`seamless hooks`, `seamless claims`) | Not released (seamless-cli#359) |
| OpenID Provider (`permissions` and `custom_claims` scopes) | 0.4.0 | Published |
| `seamless-auth-admin-dashboard` | v0.14.0 (Login hooks and Custom claims pages) | Released |
| `seamless-cli` | 0.30.0 (`seamless hooks`, `seamless claims`) | Published |

---

Expand Down
22 changes: 10 additions & 12 deletions src/content/docs/build/native-apps-oidc.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,11 +19,10 @@ the registry and the token model. This page covers what is different for native

<Aside type="note" title="Status">
Sign-in ships in v0.21 with the OpenID Provider, including sign-out and the device authorization
grant for CLIs on machines without a browser. Part of [An App With Its Own
Backend](#an-app-with-its-own-backend) is not released: account notices through a client link need
Seamless Auth API v0.23.0, which is not published yet. See [Versions](#versions). So does `seamless
profile login` through the provider, described in [A Runnable CLI
Example](#a-runnable-cli-example).
grant for CLIs on machines without a browser. Account notices through a client link, in [An App
With Its Own Backend](#an-app-with-its-own-backend), need Seamless Auth API v0.23.0. See
[Versions](#versions). So does `seamless profile login` through the provider, described in [A
Runnable CLI Example](#a-runnable-cli-example).
</Aside>

---
Expand Down Expand Up @@ -299,7 +298,7 @@ where a feature first shipped sooner.
| Public client, loopback redirect, PKCE, API tokens, refresh, revocation | The provider, from v0.21 | Edge image `seamless-auth-oidc-provider:v0.3.0` |
| `acr`, `amr` and `auth_time` on an access token for a resource | `@seamless-auth/oidc-provider` 0.3.0 | Edge image `v0.3.0` |
| Verify-only guards (`createResourceServer`) | `@seamless-auth/express` 0.23.0, with the same guards in the Fastify, Next.js, Go, Python and Rust adapters | `@seamless-auth/express` 0.24.0 |
| Client links and `clientId` on account notices | **Seamless Auth API v0.23.0, which is not published.** API v0.22.0 has no link routes. | The API built from source at [`bcab4d1`](https://github.com/fells-code/seamless-auth-api/commit/bcab4d1b62ebb1f14e9b3eda8297ede01e38962f) |
| Client links and `clientId` on account notices | Seamless Auth API v0.23.0. API v0.22.0 has no link routes. | The API built from source at [`bcab4d1`](https://github.com/fells-code/seamless-auth-api/commit/bcab4d1b62ebb1f14e9b3eda8297ede01e38962f) |

### Register Three Records

Expand Down Expand Up @@ -384,7 +383,7 @@ nobody. A link fixes that. The backend gets a client credentials token with its
the desktop app in `clientId`. The template names the app the user knows, not the backend.

<Aside type="caution" title="Needs API v0.23.0">
`clientId` and the link routes are not in a published API yet. On API v0.22.0, an application can
`clientId` and the link routes are in API v0.23.0 and later. On API v0.22.0, an application can
only send to users who hold a grant with that same application. See
[Account Notices](/build/openid-provider#account-notices-from-an-application).
</Aside>
Expand Down Expand Up @@ -462,11 +461,10 @@ keychain, or a device code that expires. The README lists exactly what it does a

### Signing In To Seamless With The Seamless CLI

<Aside type="caution" title="Merged, not released">
What this section describes is merged in
[seamless-cli#349](https://github.com/fells-code/seamless-cli/pull/349), but no published
`seamless-cli` has it yet, and it needs Seamless Auth API v0.23.0 and the provider edge. API v0.23.0
is not published. The published CLI (0.27.2) signs in to an instance with an email code.
<Aside type="note" title="Needs CLI 0.28.0 and API v0.23.0">
What this section describes is in `seamless-cli` 0.28.0 and later, and needs Seamless Auth API
v0.23.0 and the provider edge. With no provider configured, `seamless profile login` keeps the
email code.
</Aside>

`seamless profile login` follows the same rules for one more purpose: an operator signing in to an
Expand Down
9 changes: 4 additions & 5 deletions src/content/docs/build/roles-and-permissions.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,11 +15,10 @@ a catalogue of permissions, maps each role to a set of them, and the auth API pu
permissions in the access token. Your backend checks them with `requirePermission`, and your React
app can read them to show or hide UI.

<Aside type="caution" title="Needs auth API v0.23.0, not released yet">
<Aside type="note" title="Needs auth API v0.23.0">
Permissions, organization roles in the token, and every route on this page need
`seamless-auth-api` v0.23.0. The latest release is v0.22.0, which has none of them. The adapter
guards are already published (see [Versions](#versions)), and against API v0.22 they deny every
request, because no token carries permissions. Nothing fails open.
`seamless-auth-api` v0.23.0 or later (see [Versions](#versions)). Against an older API the adapter
guards deny every request, because no token carries permissions. Nothing fails open.
</Aside>

---
Expand Down Expand Up @@ -530,7 +529,7 @@ none: every check answers `false`, and `permissions`, `organizationRoles` and

| Component | First version with permissions | Status |
| ------------------------------- | ------------------------------ | ------ |
| `seamless-auth-api` | v0.23.0 | Not released. v0.22.0 is the latest |
| `seamless-auth-api` | v0.23.0 | Released |
| `@seamless-auth/core`, `express`| 0.25.0 | Published |
| `@seamless-auth/fastify` | 0.16.0 | Published |
| `@seamless-auth/nextjs` | 0.9.0 | Published |
Expand Down
24 changes: 11 additions & 13 deletions src/content/docs/build/webhooks.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,12 +16,10 @@ scheme, so any Standard Webhooks verifier checks them, and the server adapters s
Events are built from the committed audit log, delivery is retried for about 42 hours, and every
attempt is in a delivery log you can read and redeliver from.

<Aside type="caution" title="Needs auth API v0.23.0, not released yet">
Webhooks and every route on this page need `seamless-auth-api` v0.23.0. The latest release is
v0.22.0, which has none of them. `verifyWebhook` and the adapter helpers are not published yet,
and neither are the console's **Webhooks** page or the CLI's `seamless webhooks` commands (see
[Versions](#versions)). The hand-written verifiers for Go, Python and Rust work today, because
they only need the language's standard crypto.
<Aside type="note" title="Needs auth API v0.23.0">
Webhooks and every route on this page need `seamless-auth-api` v0.23.0 or later, and
`verifyWebhook` needs `@seamless-auth/core` 0.26.0 (see [Versions](#versions)). The hand-written
verifiers for Go, Python and Rust need only the language's standard crypto.
</Aside>

---
Expand Down Expand Up @@ -185,12 +183,12 @@ and when it is rotated. It cannot be read back.
The console's **Webhooks** page (`/webhooks` in `seamless-auth-admin-dashboard`) creates, edits,
turns off and on, and deletes endpoints, shows why the API turned one off, rotates its secret,
sends a test event, and has the delivery log with a dead letter view and redeliver. Every write,
including a test and a redelivery, asks for step-up first. The page is not in a console release
yet (seamless-auth-admin-dashboard#343). Against an API older than v0.23 it says it needs v0.23.
including a test and a redelivery, asks for step-up first. It is in the console from v0.14.0.
Against an API older than v0.23 it says it needs v0.23.

### With The CLI

The `seamless webhooks` commands are not in a CLI release yet (seamless-cli#359). With them:
The `seamless webhooks` commands are in `seamless-cli` 0.30.0 and later:

```bash
seamless webhooks create https://app.example.com/webhooks/seamless \
Expand Down Expand Up @@ -733,11 +731,11 @@ once, so a receiver still holding only that one starts failing. The CLI asks bef

| Component | First version with webhooks | Status |
| --------------------------------- | --------------------------- | ------ |
| `seamless-auth-api` | v0.23.0 | Not released. v0.22.0 is the latest |
| `seamless-auth-api` | v0.23.0 | Released |
| `@seamless-auth/types` | 0.39.0 | Published |
| `@seamless-auth/core`, `express`, `fastify`, `nextjs` (`verifyWebhook` and helpers) | The next minor after core and express 0.25.0, fastify 0.16.0, nextjs 0.9.0 | Not published (seamless-auth-server#279) |
| `seamless-auth-admin-dashboard` | The release after v0.13.0 (Webhooks page) | Not released (seamless-auth-admin-dashboard#343) |
| `seamless-cli` | The release after 0.29.0 (`seamless webhooks`) | Not released (seamless-cli#359) |
| `@seamless-auth/core`, `express`, `fastify`, `nextjs` (`verifyWebhook` and helpers) | core and express 0.26.0, fastify 0.17.0, nextjs 0.10.0 | Published |
| `seamless-auth-admin-dashboard` | v0.14.0 (Webhooks page) | Released |
| `seamless-cli` | 0.30.0 (`seamless webhooks`) | Published |
| Go, Python, Rust | No adapter helper. Use the verifiers above | Standard crypto only |

---
Expand Down
13 changes: 6 additions & 7 deletions src/content/docs/compare/entra-id.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -117,10 +117,10 @@ exist today.
| Lifecycle automation | **Planned for v2.0** | Lifecycle Workflows, with an ID Governance license |
| Policy | Instance sign-in settings, staged sign-in policy, step-up | Conditional Access (P1); ID Protection and risk-based Conditional Access (P2) |
| Privileged access | Break-glass admins, admin step-up | Privileged Identity Management (P2 or ID Governance) |
| Roles and permissions in the token | Organization membership roles today. A permission catalogue, role-to-permission mapping and organization roles in the token **need API v0.23.0, which is not released** | App roles and scopes in access tokens (`roles`, `scp`) |
| Roles and permissions in the token | A permission catalogue mapped to instance and organization roles; tokens carry `permissions`, `org_roles` and `org_permissions` (API v0.23.0 and later) | App roles and scopes in access tokens (`roles`, `scp`) |
| Tokens for your own APIs | Yes, through the OpenID Provider: authorization code with `S256` PKCE, client credentials, device grant (first-party), RFC 9068 JWT access tokens | Yes: expose an API with scopes, client credentials with a secret, certificate or federated credential |
| Extensibility | Logic in your own backend, behind the server adapter. Webhooks and login hooks are planned for v0.23 | Custom authentication extensions (REST calls on token issuance and other events), custom security attributes |
| Audit trail | Append-only, hash-chained auth events; NDJSON export with an integrity check | Audit and sign-in logs: 7 days on Free, 30 days on P1 and P2; export through Azure Monitor to Log Analytics, Event Hubs or storage |
| Extensibility | Signed webhooks, `post_login` and `pre_token` login hooks, and static custom claims (API v0.23.0 and later). Other logic lives in your own backend, behind the server adapter | Custom authentication extensions (REST calls on token issuance and other events), custom security attributes |
| Audit trail | Append-only, hash-chained auth events; NDJSON export with an integrity check; streaming to a SIEM over OTLP (API v0.23.0 and later) | Audit and sign-in logs: 7 days on Free, 30 days on P1 and P2; export through Azure Monitor to Log Analytics, Event Hubs or storage |
| User export | No bulk export endpoint; self-hosted, the data is in your own Postgres. Paginated admin user list and a passkey coverage report (CSV) | Microsoft Graph, and a CSV download of profile properties in the portal (preview). Microsoft documents no password hash export |
| Third-party compliance attestations | None for Seamless Auth itself | FedRAMP High and DoD IL2 (Azure public), up to IL6 (Azure Government) |
| Availability commitment | Yours, when self-hosted | Microsoft states 99.99% availability for authentication |
Expand Down Expand Up @@ -208,7 +208,6 @@ If any of these is a hard requirement today, stay on Entra ID or choose another
- **You rely on Conditional Access, risk policies or PIM.** Seamless Auth has no equivalent.
- **You need Windows sign-in, device trust, LDAP or Kerberos.** Out of scope today; RADIUS, LDAP and
forward-auth are planned for v2.1.
- **You need permissions in the token now.** That needs API v0.23.0, which is not released.
- **Other apps need a certified identity provider.** The OpenID Provider is new and not OpenID
certified.
- **You need a vendor's FedRAMP authorization or a contractual SLA for the auth service itself.**
Expand Down Expand Up @@ -292,12 +291,12 @@ Seamless Auth details (Seamless Auth API v0.22.0, OpenID Provider v0.3.0, checke

- [What Is Seamless Auth?](/start/overview), including [When Seamless Auth Is Not The Right Choice](/start/overview#when-seamless-auth-is-not-the-right-choice)
- [OpenID Provider](/build/openid-provider) and the [oauth2-proxy guide](/build/oidc-oauth2-proxy)
- [How To Use Roles And Permissions](/build/roles-and-permissions) (needs API v0.23.0, not released)
- [How To Use Roles And Permissions](/build/roles-and-permissions), [How To Receive Webhooks](/build/webhooks) and [How To Use Login Hooks And Custom Claims](/build/login-hooks-custom-claims)
- [How To Use Organizations And Memberships](/build/organizations-memberships)
- [OAuth Login](/build/oauth-login#microsoft-entra-id)
- [Migrate Users From Another Identity System](/operate/migrate-users) and [`migrate entra-id`](/reference/cli-commands#migrate-entra-id)
- [v0.20 Release Notes](/reference/release-v0-20) (recovery) and [v0.21 Release Notes](/reference/release-v0-21) (OpenID Provider)
- [v0.20 Release Notes](/reference/release-v0-20) (recovery), [v0.21 Release Notes](/reference/release-v0-21) (OpenID Provider) and [v0.23 Release Notes](/reference/release-v0-23) (roles, permissions and hooks)
- [Environment Variables](/reference/environment-variables) (`PHISHING_RESISTANT_ONLY`)
- [Auth Events and Auditing](/understand/authevents)
- Planned features: the Seamless Auth roadmap milestones v0.23, v1.1, v1.2, v2.0 and v2.1 in [seamless-auth-api](https://github.com/fells-code/seamless-auth-api/milestones)
- Planned features: the Seamless Auth roadmap milestones v1.0, v1.1, v1.2, v2.0 and v2.1 in [seamless-auth-api](https://github.com/fells-code/seamless-auth-api/milestones)
- Source: [fells-code on GitHub](https://github.com/fells-code)
Loading