Pembangun
Spesifikasi integrasi SSO·SCIM
Nilai dan gelagat yang diperlukan untuk integrasi OIDC·SAML 2.0·SCIM 2.0.
Susunan tetapan mengikut skrin, lihat SSO dan SCIM.
{API} dalam jadual ialah alamat API Keural bagi persekitaran yang digunakan (contoh: https://api.keural.ai). Gunakan alamat yang dipaparkan dalam skrin Pengurusan organisasi → Tetapan SSO.
Ringkasan nilai pendaftaran
| Item | Nilai |
|---|---|
| URI ubah hala OIDC | {API}/api/sso/callback |
| Permulaan log masuk OIDC·SAML | {API}/api/sso/{orgId}/login |
| SAML SP EntityID | {API}/api/sso/saml/metadata |
| SAML ACS URL | {API}/api/sso/saml/callback |
| SCIM Base URL | {API}/scim/v2 |
Log masuk sentiasa dimulakan dari Keural (SP-initiated). Apabila e-mel dengan domain yang didaftarkan dimasukkan pada skrin log masuk, anda dibawa ke alamat permulaan log masuk. Jika berjaya, anda dibawa ke skrin utama Keural. Jika gagal, anda dibawa ke /login?error=sso.
OIDC
| Item | Gelagat |
|---|---|
| Aliran | Authorization Code |
| Permintaan authorize | response_type=code, client_id, redirect_uri, scope=openid email profile, state, nonce |
| state · nonce | Sekali guna dan sah selama 10 minit. Jika tetingkap log masuk dibiarkan terbuka melebihi 10 minit, log masuk perlu bermula semula dari awal. |
| Pertukaran token | POST ke token endpoint, application/x-www-form-urlencoded, pengesahan klien client_secret_post (client_id dan client_secret dalam badan) |
| Tandatangan ID token | Hanya menerima RS256. Kunci dicari dalam jwks_uri mengikut kid. |
| Pengesahan ID token | Tandatangan, exp, aud mengandungi client_id, nonce sepadan, iss sepadan dengan Issuer URL (/ di hujung diabaikan) |
| E-mel | Tuntutan email dalam ID token. Jika tiada, userinfo endpoint dipanggil dengan Authorization: Bearer <access_token> untuk membaca email. |
| Nama | Tuntutan name dalam ID token |
| Endpoint | Dicari dalam /.well-known/openid-configuration pada Issuer URL. IdP yang tidak menyediakannya boleh diisi terus dengan alamat authorization · token · JWKS · userinfo melalui Papar tetapan lanjutan. |
| Had masa | 15 saat bagi setiap panggilan IdP |
Aplikasi IdP mesti membenarkan client_secret_post. Jika tetapan hanya membenarkan client_secret_basic atau private_key_jwt, pertukaran token akan gagal.
SAML 2.0
| Item | Gelagat |
|---|---|
| Permintaan | AuthnRequest dihantar melalui pengikatan HTTP-Redirect. Permintaan tidak ditandatangani. |
| Kandungan permintaan | Destination=IdP SSO URL, AssertionConsumerServiceURL=ACS URL, ProtocolBinding=HTTP-POST, Issuer=SP EntityID, NameIDPolicy Format=…:nameid-format:unspecified, AllowCreate=true |
| Respons | Pengikatan HTTP-POST, dengan SAMLResponse dan RelayState. RelayState mesti dikembalikan sama seperti nilai yang dihantar Keural. |
| Tandatangan | Response atau Assertion mesti mempunyai tandatangan yang sah. Kunci pengesahan hanya menggunakan sijil yang didaftarkan dalam skrin. |
| Assertion | Respons mesti mengandungi tepat satu assertion. EncryptedAssertion tidak diterima. |
| Status | StatusCode ialah urn:oasis:names:tc:SAML:2.0:status:Success |
| Issuer | Jika IdP EntityID diisi, ia mesti sepadan dengan Issuer dalam assertion |
| Syarat | NotBefore dan NotOnOrAfter (toleransi 300 saat), Audience=SP EntityID |
| SubjectConfirmationData | Recipient=ACS URL, NotOnOrAfter (toleransi 300 saat), InResponseTo=ID permintaan yang Keural hantar |
| E-mel | Atribut Name atau FriendlyName ialah salah satu daripada berikut (tidak peka huruf besar/kecil): email, mail, emailAddress, E-Mail-Addresses, http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress. Jika tiada, NameID yang mengandungi @ digunakan. |
| Nama | displayName, name, cn, http://schemas.microsoft.com/identity/claims/displayname |
| Sijil | X.509 satu buah. PEM atau Base64(DER). Untuk menukar sijil, masukkan sijil baharu dan simpan. |
| Metadata | Daripada memuat naik XML metadata IdP, masukkan tiga nilai: IdP EntityID · IdP SSO URL · sijil. |
Padanan pengguna
| Item | Gelagat |
|---|---|
| Syarat dihantar ke SSO | Bahagian selepas @ dalam e-mel sama tepat dengan satu item dalam senarai domain e-mel (tidak peka huruf besar/kecil). Subdomain didaftarkan secara berasingan. |
| Mencari akaun | Akaun Keural dicari menggunakan e-mel (huruf kecil) yang diberikan IdP. |
| Apabila akaun tiada | Jika Cipta pengguna automatik pada log masuk pertama (JIT) dihidupkan, akaun dicipta. Jika dimatikan, log masuk ditolak. |
| Sertai organisasi | Jika bukan ahli organisasi, pengguna menyertai sebagai Ahli. Akaun yang tempat duduknya penuh atau yang tergolong dalam organisasi lain tidak menyertai dan hanya dapat log masuk. |
| Syarat simpan domain e-mel | Domain yang disahkan dengan DNS TXT, tidak termasuk domain e-mel awam |
Pengesahan domain
| Item | Nilai |
|---|---|
| Jenis rekod | TXT |
| Hos | Domain yang didaftarkan sama seperti yang dimasukkan (contoh: acme.com). Jangan gunakan subdomain awalan. |
| Nilai | keural-verify=<UUID> (nilai tepat seperti yang dipaparkan) |
| Masa semakan | Disemak sekali apabila Sahkan pengesahan ditekan. |
SCIM 2.0
| Item | Nilai |
|---|---|
| Base URL | {API}/scim/v2 |
| Pengesahan | Authorization: Bearer <token SCIM>. Token bermula dengan scim_ dan hanya dipaparkan sekali semasa dikeluarkan. |
| Content-Type | Permintaan application/scim+json atau application/json, respons application/scim+json |
| Kod status | Dikembalikan sebagai kod status HTTP sebenar. Badan ralat ialah format SCIM Error (schemas, status, detail, scimType). |
Endpoint
| Kaedah | Laluan | Gelagat |
|---|---|---|
GET | /Users | Senarai. filter=userName eq "…", startIndex (lalai 1), count (lalai 100, maksimum 200) |
GET | /Users/{id} | Lihat seorang pengguna |
POST | /Users | Cipta (201). Jika e-mel yang sama wujud, 409. |
PATCH | /Users/{id} | Ubah active, displayName, name.formatted, name.givenName |
PUT | /Users/{id} | Gunakan displayName·name·active. Jika active tidak disertakan, ia dianggap aktif. |
DELETE | /Users/{id} | Gantung akaun (204). Data tidak dipadam. |
GET | /Groups, /Groups/{id} | Lihat dua kumpulan tetap. filter=displayName eq "…" |
PATCH | /Groups/{id} | Tambah, buang, atau gantikan ahli |
GET | /ServiceProviderConfig, /ResourceTypes, /Schemas | Lihat ciri yang disokong |
Atribut pengguna
| Atribut | Kegunaan |
|---|---|
userName | E-mel. Jika tiada, emails[0].value digunakan. |
displayName · name.formatted · name.givenName+name.familyName | Nama paparan |
active | false menggantung (log masuk disekat), true memulihkan |
id | ID pengguna Keural. Dimuatkan dalam respons. |
externalId tidak disimpan. Untuk mencari pengguna dari IdP, gunakan penapis userName.
Kumpulan
| id | displayName | Apabila ahli ditambah | Apabila ahli dibuang |
|---|---|---|---|
keural-admins | Keural Admins | Pentadbir | Ahli |
keural-members | Keural Members | Ahli | Tiada perubahan |
Peranan pemilik organisasi tidak berubah melalui SCIM. Mencipta atau memadam kumpulan (POST·DELETE /Groups) memulangkan 501. value bagi ahli kumpulan ialah ID pengguna Keural (id daripada /Users).
Skop sokongan
| Ciri | Disokong |
|---|---|
| PATCH | Ya |
| Penapis | userName eq, displayName eq |
| Bulk · isihan · ETag · tukar kata laluan | Tidak |
Ralat
| Status | scimType | Punca |
|---|---|---|
400 | invalidValue | userName dan emails kedua-duanya tiada |
401 | — | Token tiada atau salah, pemperuntukan SCIM dimatikan |
404 | — | Bukan pengguna atau kumpulan dalam organisasi ini |
409 | uniqueness | Akaun dengan e-mel yang sama sudah wujud, tempat duduk melebihi had |
501 | — | Mencipta atau memadam kumpulan |