OIDC Reference

The complete wire contract: endpoints, protocol requirements, parameters, claims, and errors. Discovery is live at https://factor.octetproof.com/.well-known/openid-configuration.

Endpoints

Protocol requirements

LFA implements the authorization-code flow, deliberately narrow and strict:

/authorize parameters

Beyond the standard authorization-code parameters:

Signed request objects (brokers)

Identity brokers (Okta's IdP-Authenticator "Factor only", Microsoft Entra ID, Auth0) run a fixed, standard token exchange and cannot add the octet_user_id that a direct client sends at /token. A broker instead authenticates the front channel: it signs its /authorize request as a JWS and passes it as request=<JWS>, and the user it binds is taken from inside that signed object.

A client is a broker only when Octet has configured a server-side broker section for it, holding an expected issuer and a set of pinned request-signing public keys that you supply to Octet. This is fail-closed: once a client is a broker, an /authorize without a valid signed object is rejected. For a direct client a stray request= is ignored.

Parameters inside the signed object take precedence over the query string: response_type, redirect_uri, scope, state, nonce, the PKCE challenge and method, acr_values, and octet_policy_id.

/token parameters

Beyond the standard code-exchange parameters (grant_type, code, redirect_uri, client credentials, code_verifier):

There are two binding sources, depending on the client:

• Direct clients send octet_user_id on the RP-authenticated /token, as documented above, and use octet_device_enroll for device replacement.
• Broker clients bind on the login_hint from the signed request object at /authorize (see Signed request objects) and cannot send octet_user_id or octet_device_enroll. Enrollment is forced off, so a new or different device for an already-bound user is rejected (invalid_grant). Recovery is an admin revoke via POST /v1/device/revoke, after which the next login TOFU-binds the new phone. A broker session that reaches /token with no authenticated hint is rejected regardless of App Attest.

The token response:

{
  "token_type": "Bearer",
  "access_token": "…",
  "id_token": "…",
  "location_assertion": "…"
}

location_assertion is a top-level mirror of the octet_location_assertion claim, for stacks that do not want to open a nested JWT.

id_token claims

Why brokers get identity claims and direct clients do not

A direct client's login_hint is an ordinary query parameter. Anyone can put any value there, so reflecting it into email or preferred_username would let a caller impersonate someone to their own RP. A broker's hint arrives inside a signature-verified request object, signed by a key LFA has pinned, and LFA returns it only to the party that signed it. That is not LFA vouching for an identity. It is handing back the broker's own assertion, which is why email_verified stays false.

GET /userinfo

Returns the same identity claims as the id_token: sub, octet_login_hint, and (for brokers) preferred_username, email, email_verified. Some products build their user profile from UserInfo rather than the id_token, so the two are kept identical by design. Present the access token as a bearer token. An id_token or location assertion is rejected with 401.

The Location Assertion

A compact ES256 JWS, verifiable against the same JWKS, asserting the region verdict for this login. It expires 120 seconds after issue and is bound to the login's nonce. It is an audit-grade statement of presence at that moment, not a credential. The subject is device-rooted (the enrolled device, not your user id), so the assertion can be verified downstream without carrying your user identifiers.

POST /v1/device/revoke

Revokes the device bound to one of your users. This is the lost or stolen phone switch. See Device lifecycle.

Errors