Mwongozo wa kuunganisha

shule.id inawaingiza wanafunzi na walimu kwenye programu yako kwa OpenID Connect. Baada ya ukaguzi, programu yako inaweza pia kujua kama mtu ni mwanafunzi aliyesajiliwa.

Anwani za huduma

Discovery URL: https://auth.staging.shule.id/.well-known/openid-configuration
Issuer: https://auth.staging.shule.id
Grant type: Authorization code, pamoja na PKCE (S256)
Client authentication: client_secret_basic

Hatua

Sajili shirika lako. Utakuwa msimamizi wake.
Unda programu. Inaanza katika hali ya Majaribio ikiwa na openid, profile na email; utapata kitambulisho cha mteja na siri ya mteja.
Weka thamani zilizo hapo juu kwenye mteja wako wa OIDC.
Omba ruhusa zinazokaguliwa kwenye ukurasa wa programu: Matumizi rasmi kabla ya kuzindua, na Uthibitisho wa mwanafunzi ukiuhitaji.

Scopes na taarifa (claims)

Tuma scopes unazohitaji, zikitenganishwa kwa nafasi. shule.id hupuuza scopes isizozijua bila kuonyesha hitilafu, kwa hiyo andika scope ya uthibitisho wa mwanafunzi jinsi ilivyo hapa.

openid
- sub 318094117346582529 userinfo + access token
profile
- name Neema Juma userinfo
- given_name Neema userinfo
- family_name Juma userinfo
- preferred_username neema.juma27 userinfo
- locale sw userinfo
- updated_at 1794195138 userinfo
- shule:username neema.juma27 userinfo + access token
email
- email neema.juma27@shule.id userinfo
- email_verified true userinfo
offline_access

Haina taarifa. Inaipa programu refresh token.
Uthibitisho wa mwanafunzi Inahitaji ukaguzi

urn:zitadel:iam:org:project:role:student_status
- student_status {"institution":"mfano","institution_name":"Shule ya Sekondari Mfano","stage":"o-level","enrolled_until":"2026-12-31"} userinfo + access token
Tuma maandishi haya kama yalivyo. student_status peke yake au shule:student_status hupuuzwa bila hitilafu, na tokeni haibebi uthibitisho wa mwanafunzi.

student_status hutumwa kwenye userinfo na access token, pale tu mtumiaji anaporidhia na akiwa na usajili hai uliothibitishwa.

Majaribio na Matumizi rasmi

Majaribio: Wanachama wa shirika lako na akaunti za majaribio pekee ndio wanaweza kuingia.
Matumizi rasmi: Mtu yeyote mwenye akaunti ya shule.id anaweza kuingia.

Ruhusa zilizokaguliwa

teKsafari inakagua kila ombi.

Matumizi rasmi: Inaruhusu mtu yeyote mwenye akaunti ya shule.id kuingia, si wanachama wako na akaunti za majaribio pekee.
Uthibitisho wa mwanafunzi: Inaongeza taarifa ya student_status: taasisi, ngazi na tarehe ya mwisho ya usajili, kwa watumiaji wanaoridhia.
Barua kwa wanafunzi chini ya miaka 18: Inaruhusu kikoa chako cha kutuma barua kufikia masanduku ya barua ya wanafunzi walio chini ya miaka 18. teKsafari inakagua kikoa na unachotuma.

Mfano

Weka Client ID na redirect URI ya programu yako, na hifadhi siri kwenye SHULE_CLIENT_SECRET.

Node.js

// npm install openid-client
import * as oidc from "openid-client";

const config = await oidc.discovery(
  new URL("https://auth.staging.shule.id"),
  "YOUR_CLIENT_ID",
  undefined,
  oidc.ClientSecretBasic(process.env.SHULE_CLIENT_SECRET),
);

// 1. Send the user to shule.id. Keep verifier and state in the user's session.
const verifier = oidc.randomPKCECodeVerifier();
const state = oidc.randomState();
const signInUrl = oidc.buildAuthorizationUrl(config, {
  redirect_uri: "https://your-app.example/auth/callback",
  scope: "openid profile email urn:zitadel:iam:org:project:role:student_status",
  code_challenge: await oidc.calculatePKCECodeChallenge(verifier),
  code_challenge_method: "S256",
  state,
});

// 2. On https://your-app.example/auth/callback: exchange the code, then read the claims.
//    currentUrl is the full URL shule.id redirected to, with its ?code= and &state=.
const currentUrl = new URL(req.url, "https://your-app.example/auth/callback");
const tokens = await oidc.authorizationCodeGrant(config, currentUrl, {
  pkceCodeVerifier: verifier,
  expectedState: state,
});
const claims = await oidc.fetchUserInfo(config, tokens.access_token, tokens.claims().sub);