Contract
What the IdP is
The boundary between IdP Urupema and every app. The IdP answers who a person is; the app decides what that person may do.
IdP Urupema is the institutional authority for identity and authentication at Instituto Urupema: one stable identity per person, authentication, session management, and a standard signed proof of identity for every app, OpenID Connect. Keycloak is the current engine, not the contract: no app depends on a Keycloak API, object, role or database; the engine is replaceable without changing any app.
These pages are the contract. Your app must marks an obligation of the app that the IdP cannot enforce. The IdP guarantees marks a rule the IdP enforces on every deploy and proves in its test suite.
Who owns what
Section titled “Who owns what”| Meaning | Owner of the truth |
|---|---|
| Who the person is; credentials; verified email | the IdP |
| Whether the account is still valid now | the IdP (the app session is derived from it) |
| Which apps exist as clients | the IdP: one reviewed descriptor per app (Registering an app) |
| Whether this person may do X in your app | your app |
| Profiles, roles, groups, teams and relationships specific to your app | your app |
| The audit trail of actions in your app | your app |
| Technical authentication events (logins, admin actions) | the IdP, kept 30 days |
Authorization stays in your app. An account proves identity only: it is not a relationship with the Institute, not an academic affiliation and not a permission in any app. A new account has zero permissions in your app until your app grants some. See Identity and access.
A new account carries nothing. Its tokens hold no role beyond the protocol defaults; the IdP’s admin API refuses it.
Speak only the protocol. Discovery, Authorization Code with PKCE, token validation against the published keys, exact redirects, logout through the published endpoint. Never the Keycloak admin API, its database or an administrative credential.
What the IdP offers
Section titled “What the IdP offers”- Sign-in with Authorization Code + PKCE S256 for confidential (server) and public (native) clients (Issuer and OIDC profile).
- A closed set of claims:
sub,name,preferred_username,email,email_verified(Claims). - Single sign-on across every app of the Institute, a central session the app session derives from, revocation within 5 minutes, single logout of the current session (Session and logout).
- Accounts with verified email, password recovery and brute-force protection, run by the IdP (Accounts).
Not offered
Section titled “Not offered”| Not offered | Do instead |
|---|---|
| An admin API for apps (list, create, disable or delete users; read sessions) | Keep your own records keyed by (iss, sub) and decide access there. Blocking someone from the whole Institute is an IdP administration act, not an app’s |
| Roles, groups or app-specific claims in tokens | Keep roles in your app. A new claim enters the contract only with a real source of truth, a stable meaning and a need shared by several apps, never to carry authorization |
Scopes beyond openid profile email (roles, phone, address, offline_access…) | Request exactly openid profile email; any other scope gets invalid_scope |
Long-lived offline sessions (offline_access) | Re-authenticate; the central session lasts up to 10 hours |
| Implicit flow, password grant, client credentials | Authorization Code + PKCE S256 |
| A token for another app’s API (token exchange) | Not yet: arrives with the agents phase. A token serves only the client that requested it |
| Sign-in for MCP servers and AI agents acting for a person | Not yet: planned as Gate 2 |
| Login with CAFe or gov.br | Not yet. When added, it is brokered inside the IdP: same (iss, sub), no change in your app |
| Back-channel logout notifications | The app session ends at the next refresh, at most 5 minutes after the central session ends |
Evolution rule
Section titled “Evolution rule”One side changes without forcing the other: a new sign-in method without changing apps, a new app without changing the IdP, a new attribute without it becoming authorization, a new engine without rewriting apps. A change that forces apps to know Keycloak, carries business rules in the token or queries an administrative API breaks the architecture.