Skip to content

Repository navigation

Specbook 0.2.0

Choose a tag to compare

View all tags
@ajaishankar ajaishankar released this 16 Oct 00:16
· 86 commits to main since this release
v0.2.0
041abcc

Sign in to OAuth APIs from the browser, and every server a spec lists is now an environment.

New

  • Sign in with OAuth 2.0 and OpenID Connect. When a spec declares an authorization code flow, or an OpenID
    Connect provider, the credentials prompt offers Sign in. It uses PKCE, so there is no client secret. The
    token stays in the tab, is bound to the API's origin, and is applied through the same {{secrets.*}}
    substitution as a pasted value. Pasting a token still works, and is the fallback if the provider will not talk
    to a browser.
  • Every servers entry is an environment. Opening a spec with production, sandbox and regional servers now
    gives you each of them in the Environment picker, not just the first. The first stays live; the others are
    named from their description. Credentials are kept per API origin, so a key typed for one server's host is not
    sent to another's.

Setting up sign-in

Register a public client (no secret) with your provider and allow this redirect URI:

https://ui.specbook.dev/oauth/callback/

It is a page that does not change when the viewer's version does. On a viewer you embed or host yourself the
address is your page's own, and specbook dev and specbook preview print theirs. Enter the client id in the
prompt. Sign-in works from an embedded viewer, and needs a secure page (https, or localhost).

Improved

  • The response is shown as soon as a request has been sent.
  • The sign-in prompt, and the example links on the landing page, are laid out for a phone.
  • Third-party notices ship with the built viewer.
  • Fixed a stale landing-page stylesheet meeting new markup after a deploy.
  • Fixed a rare half-read of specbook.json while another generate was writing it.

Good to know

  • A scheme has one sign-in provider for all its environments. If an environment signs in somewhere else, paste a
    token there.
  • From the hosted viewer or a static build the token exchange is made by the browser, so the provider must allow
    calls from the page's origin: add https://ui.specbook.dev to its allowed (web) origins. In specbook dev and
    preview it goes through the dev server's proxy, so that is not needed.
  • A viewer framed inside another site's page completes sign-in only with providers that do not cut the
    window's opener (a provider can, with a Cross-Origin-Opener-Policy header). Embed the script, host the viewer
    yourself, or paste a token there.
  • Providers that need a client secret at the token endpoint cannot be used from a browser; paste a token instead.
  • Refresh tokens are not handled yet: sign in again when a token expires.

No breaking changes. Config gains an optional oauth setting on auth profiles, and @specbook/core exports the
new OAuth and server helpers.

Sign-in is tested against a real Keycloak in Docker (pnpm test:oauth, also run weekly).

Full changelog: v0.1.0...v0.2.0

Assets 4
Loading