Token exchange for user impersonation
Tesouro supports OAuth 2.0 Token Exchange (RFC 8693). Your application exchanges a user JWT from your OIDC provider for a Tesouro access token scoped to that user.Request
Response
Your JWT must include the user’s unique identifier in the
sub claim and their email in the
email claim.Users can only be impersonated within their assigned application context. Cross-application
impersonation is prevented.
Widget authentication
Embedded components run in the browser, so they can’t hold your client secret. Your backend gives them a widget token instead: an encrypted JWE (RFC 7516) that wraps a token exchange request for the signed-in user. Tesouro decrypts it, runs the exchange, and returns an access token scoped to that user. Node backends can use Tesouro’s token package instead of building the token. Any other backend builds it as described below.Tesouro provides
TESOURO_CLIENT_ID, TESOURO_CLIENT_SECRET, and TESOURO_WIDGET_SECRET
(exactly 32 bytes) during onboarding. To request them, have your designated team lead submit an
access request. Keep all three on your
server.Payload
The payload is the token exchange request, and it’s what gets encrypted.organization_reference is required. Tesouro uses it to group applications under the
business, including before the applicant has a Tesouro user, so the components find the right
application when they load. Resolve this value on your backend, and never accept it from the
browser.Subject token
subject_token is an unsigned JWT: the base64url-encoded header, a period, the base64url-encoded payload, and a trailing period in place of a signature. The header is {"alg":"none","typ":"JWT"}.
Encryption
Encrypt the payload as a JWE in compact serialization, with this protected header:
The key is the UTF-8 bytes of your widget secret, which must be exactly 32 bytes.
Lifetime
Keep widget tokens short-lived, and mint a fresh one each time the components ask your backend for one. Your token endpoint returns the token’sexp alongside it, so the components know when it expires.
Users
The Users guide covers the model behind these tokens: what a user is, how thesub and email claims map to a Tesouro identity, which token to issue when, and how to add users beyond the primary controller.