Integrate
Start here
The path from zero to an app in production with IdP Urupema, and the architecture choice made first.
App shape
Section titled “App shape”| Your app | Client profile | What to follow |
|---|---|---|
| Has a server (any web app with a backend, including a single-page app served by it) | confidential | Node.js server (BFF): the server does the login and keeps the tokens; the browser gets only a session cookie. Recommended. |
| An API called by your own app | none of its own: it accepts the app’s tokens | API: validate the token |
| A native or mobile app with no server of its own | public (no secret, PKCE only) | The platform’s OIDC library (AppAuth on iOS and Android); the contract applies unchanged |
A browser-only app holding tokens in JavaScript is allowed by the contract (public profile). Serve it instead from a small server that does the login: tokens never reach the browser. The review of a registration assumes that shape.
Other server stacks: a maintained OpenID Connect client library that does Authorization Code with PKCE S256, sends a nonce and verifies the ID token signature, plus the contract. The Node.js server is the reference: every rule is visible in its code.
-
Register two clients by pull request:
my-app-dev(localhost) now,my-app(production) at deploy. One descriptor per environment, inclients/of urupema/idp, or by e-mail to suporte@institutourupema.com.br without access to it. See Registering an app. -
Receive the client secret over a secure channel once the pull request is merged and applied. It goes into the server’s environment only: never into the repository, the browser or a log.
-
Implement the login by copying the Node.js server: discovery, login, callback, derived session, logout. With an API, add token validation.
-
Grant access in your app, not in the IdP. A new account has zero permissions in the app; the app grants them, keyed by
(iss, sub). See Identity and access. -
Prove it with the before production list, then register the production client.
Server configuration
Section titled “Server configuration”| Variable | Value |
|---|---|
IDP_ISSUER | https://id.institutourupema.com.br/realms/urupema |
IDP_CLIENT_ID | the descriptor’s clientId, e.g. my-app-dev |
IDP_CLIENT_SECRET | delivered after registration (confidential clients only) |
APP_URL | the app’s base URL; ${APP_URL}/callback must be exactly one of the descriptor’s redirectUris |
No other configuration: no endpoint URLs, no keys, no realm name. They come from discovery.