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 only the authorization-code flow, with these requirements:

/authorize parameters

Beyond the standard authorization-code parameters:

Signed request objects (brokers)

Identity brokers, such as Okta's IdP-Authenticator "Factor only", 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 client when Octet has registered your broker's issuer and request-signing public keys for it. 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). To recover, ask Octet to revoke the binding with POST /v1/device/revoke. The next login binds the new phone automatically. A broker session that reaches /token with no authenticated hint is rejected regardless of attestation.

The token response:

{
  "token_type": "Bearer",
  "access_token": "…",
  "expires_in": 120,
  "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. LFA does not vouch for the identity. It returns 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 return the same identity claims. 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 a statement of presence at that moment, for audit use, 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. Use it when a phone is lost or stolen, and to move a broker user to a new phone. Direct clients call it themselves. Broker clients hold no client secret, so Octet calls it for them. See Device lifecycle.

Errors