Developer guide

Everything a team needs to sign people in to their own tool through CEGIS Tools. This is an OpenID Connect provider, so you do not implement a protocol — you point a library at one URL and fill in four values.

Your tool receives a signed statement about one person, addressed to your tool, and mints its own session from it. It never sees a password, a sign-in code, or this site’s session cookie.

How sign-in flows

Your tool keeps its own landing page, public, with a Sign in button. That button goes to your own server, which sends the person here, and we send them back to you with proof of who they are.

The one place teams go wrong is pointing the button straight at this portal. It has to go through your server first — step 2 below explains why.

1. 1
   Your toolhttps://yourtool.tools.cegis.org/

   Your landing page

   Public, and it stays public — no redirect, no session yet. Someone reads what the tool does and presses Sign in.

2. 2
   Your toolhttps://yourtool.tools.cegis.org/auth/login

   Your server starts the flow

   The button points here, at your own server — not at this portal. Your server generates a state, a nonce and a PKCE verifier, keeps them, and redirects the browser onward. This is the step that cannot happen in the browser: a verifier the browser can read is a verifier an attacker can read.

3. 3
   This portalhttps://tools.cegis.org/oauth/authorize

   We check the request and sign them in

   We verify your client ID and that the redirect URI is one you registered, then sign the person in with a code emailed to them. If they already have a session here, they are not asked again — that is the single sign-on part.

4. 4
   Your toolhttps://yourtool.tools.cegis.org/auth/callback?code=…

   Back to you, with a one-time code

   The browser returns to the exact redirect URI you registered. The code is single-use and lasts 60 seconds. Check the state matches the one you stored, and reject anything that is not a GET.

5. 5
   Your toolPOST /oauth/tokenserver to server

   Your server exchanges the code

   Your server calls us directly, with your client secret and the PKCE verifier from step 2. The browser is not involved and never sees the secret or the token.

6. 6
   Your tool

   Verify, then mint your own session

   Verify the ID token against our published keys — checking iss, aud and your nonce — then set your own cookie on your own origin and send them into the tool. From here on the person is signed in to your tool, by your rules.

The four values

Ask a CEGIS administrator to register your tool. You will be given a client ID and a client secret — the secret is shown once, so put it somewhere durable before you close the page.

Then point any conforming library at the discovery document and it configures itself — openid-client (Node), authlib (Python), Spring Security, mod_auth_openidc, oauth2-proxy:

https://tools.cegis.org/.well-known/openid-configuration

Open the discovery document — it is public, and it lists every endpoint and the signing keys.

Redirect URIs, and developing locally

Every callback URL you use must be registered in full. The match is an exact string comparison — not a prefix, not an origin, not a pattern. So /auth/callback does not authorise /auth/callback/. If your framework uses more than one callback path, register each; it is one line of configuration per URL.

That strictness is deliberate. Nearly every well-known authorization-code leak has come from a redirect check that tried to be cleverer — a prefix match lets an attacker append to your callback, and an origin match lets any open redirect on your own domain carry the code away.

There is also a development deployment of this portal, with its own database, its own signing key and its own issuer. A client registered there does not exist here, and a token from one will not verify against the other, so a tool should read all four values from its environment rather than hardcoding them.

What your tool receives

The ID token is a signed JWT. Verify it — do not decode it — against the keys at https://tools.cegis.org/.well-known/jwks.json, checking iss, aud and your nonce.

{
  "sub": "8f1c…",                    // stable user id — key your records on this
  "email": "officer@karnataka.gov.in",
  "email_verified": true,
  "name": "A Officer",
  "https://cegis.org/organisation": "Department of Rural Development",
  "https://cegis.org/is_staff": false,
  "https://cegis.org/role": "user"
}

• sub is the identifier to store, not the email. The address is verified, but people change them; sub does not move.
• name and organisation are free text the user typed about themselves. Display them, escape them, and never put them into SQL, a shell command or a template unescaped.
• is_staff means a CEGIS Workspace account was asserted by Google — not that the address happens to end in cegis.org. Anyone can type such an address into the email form.
• role is this portal’s role, not yours. It says who administers this catalogue. A tool that treats it as an authorisation decision has imported a model it did not design.

What your tool is responsible for

Everything after identity. This portal says who someone is. It does not say what they may do inside your tool, and it never sees your data. Roles, per-record permissions, anything sensitive behind a second check — all yours.

Four of these fail silently rather than loudly, which is why they are worth stating rather than leaving to a library’s defaults:

• PKCE is mandatory. code_challenge_method=S256. The authorize endpoint refuses a request without it, and refuses plain.
• Check state on the way back. It ties the response to the request your server started. Without it, someone can complete a sign-in of their choosing in a victim’s browser.
• Verify aud. A token minted for another tool is not evidence about a session with yours.
• Return 405 for anything that is not a GET on your callback. A cross-origin client may send a CORS preflight there first, and an OPTIONS handled as the callback consumes the one-time state — after which the real navigation fails with an error that explains nothing.
• Set your own cookie, on your own origin, HttpOnly and SameSite=Lax. You never receive or read this site’s session cookie — it is host-only and is never sent to a tool. That is what keeps one compromised tool from becoming every tool.

Signing out

/oauth/logout ends the portal session. It cannot reach into each tool and end theirs — a tool’s cookie is on its own origin. Back-channel logout is not implemented.

Stated plainly because it surprises people: after signing out here, the next tool will ask for credentials again, but a tool already open may stay open until its own session lapses. A tool handling sensitive material should keep its session short.

When it does not work

Getting started

Tell us the tool’s name, the subdomain you want under tools.cegis.org, and every redirect URI it will use. You will get a client ID and secret back, and your tool stays unpublished — invisible in the catalogue, and unable to sign anyone in — until you say it is ready.

About these tools · Privacy policy