Documentation/Developers
Back
  • Getting started
    • Frontends and app types
    • Environments and endpoints
  • OAuth clients
    • Client ID and secret
    • Redirect URIs and start URL
    • Secret rotation
  • Login with appsolut
    • Authorization code flow
    • Tokens and claims
    • Frontend role
    • Sign-out
    • Revocation and issued tokens
    • Token endpoint errors
  • Frontend keys
    • Issue and store a key
    • Send a key
    • Rotate and revoke
  • Members API
    • Eligibility from a backend
    • The signed-in member
    • Results, rate limits and errors
    • Is an applicant an eligible member?
    • The signed-in frontend user's membership
  • appsolut register API
    • Implement the API
    • Connect and test
    • Verify a member with their challenge code
    • List every member
    • The status of several members
    • The status of one member
    • The person data of several members
    • The person data of one member
    • The claims of several members
    • The claims of one member
    • Health check

Login with appsolut

Sign frontend users in with OAuth 2.1 and OpenID Connect.

Login with appsolut is the one sign-in for all of an organisation's frontends. Your frontend sends the browser to the Studio's OAuth 2.1 server; the organisation-branded sign-in surface signs the person in or up, runs the membership check and sends them back with an authorization code; your backend exchanges the code for tokens.

A person's account with one organisation is a frontend user. The same person at two organisations is two unrelated frontend users, and a frontend user is never a Studio user. The first sign-in also onboards them as a member, where the frontend asks for it.

The protocol, in short

  • Authorization code with PKCE, as in OAuth 2.1, with PKCE method S256 and the scope openid only.
  • A confidential client: your backend authenticates to the token endpoint with HTTP Basic.
  • Tokens are JWTs signed with the key in JWKS. The access token carries the user's email, names, the organisation (tenant_id) and the frontend role (frontend_role); the ID token and UserInfo carry only sub.

OIDC discovery

Read the configuration once, from your backend:

GET <auth>/.well-known/openid-configuration
apikey: <publishable key>

Discovery advertises more than you may use. It lists the PKCE method plain, the client authentication methods client_secret_post and none, the signing algorithm HS256 and the scopes email, profile, phone and offline_access. Use only what these pages name: PKCE S256, client_secret_basic, the scope openid, and the algorithm of the key in JWKS.

Before you start

You need the client ID and secret (see OAuth clients), the two origins <auth> and <studio> with the publishable key (see Environments and endpoints), and the organisation's ID to check tenant_id.

In this section

  • Authorization code flow: start, sign-in, callback and refresh, and the rules behind them.
  • Tokens and claims: what the tokens carry, and how to check them.
  • Frontend role: what frontend_role tells you, and when it changes.
  • Sign-out: signing a user out in two steps.
  • Revocation and issued tokens: what ends a session, and what a token already issued still does.
  • Token endpoint errors: the answers a code exchange or refresh can get.