Entwickler
SSO- und SCIM-Integrationsspezifikation
Werte und Verhalten, die für die Einrichtung der OIDC-, SAML-2.0- und SCIM-2.0-Integration erforderlich sind.
Die Einrichtungsschritte am Bildschirm finden Sie unter SSO und SCIM.
In der folgenden Tabelle steht {API} für die Keural-API-Adresse der von Ihnen verwendeten Umgebung (z. B. https://api.keural.ai). Den tatsächlichen Wert übernehmen Sie aus Organisationsverwaltung → SSO-Einstellungen, wo er angezeigt wird.
Übersicht der Registrierungswerte
| Element | Wert |
|---|---|
| OIDC-Redirect-URI | {API}/api/sso/callback |
| OIDC·SAML-Anmeldestart | {API}/api/sso/{orgId}/login |
| SAML-SP-EntityID | {API}/api/sso/saml/metadata |
| SAML-ACS-URL | {API}/api/sso/saml/callback |
| SCIM-Basis-URL | {API}/scim/v2 |
Die Anmeldung beginnt immer bei Keural (SP-initiated). Wenn Sie auf der Anmeldeseite eine E-Mail-Adresse einer registrierten Domain eingeben, werden Sie zur Anmeldestart-Adresse weitergeleitet. Nach erfolgreicher Anmeldung gelangen Sie zur Startseite von Keural; bei einem Fehler wird nach /login?error=sso weitergeleitet.
OIDC
| Element | Verhalten |
|---|---|
| Ablauf | Authorization Code |
| authorize-Anfrage | response_type=code, client_id, redirect_uri, scope=openid email profile, state, nonce |
| state · nonce | Einmalig verwendbar und 10 Minuten gültig. Bleibt das Anmeldefenster länger als 10 Minuten offen, beginnt die Anmeldung von vorn. |
| Token-Austausch | POST an den Token-Endpoint, application/x-www-form-urlencoded. Die Client-Authentifizierung ist client_secret_post (client_id und client_secret im Body). |
| Signatur des ID-Tokens | Es wird nur RS256 akzeptiert. Der Schlüssel wird über kid in jwks_uri gesucht. |
| Prüfung des ID-Tokens | Signatur, exp, aud mit client_id, übereinstimmendes nonce, und iss gleich der Issuer-URL (abschließendes / wird ignoriert). |
Der Claim email des ID-Tokens. Fehlt er, wird der Userinfo-Endpoint mit Authorization: Bearer <access_token> abgefragt und daraus email gelesen. | |
| Name | Der Claim name des ID-Tokens |
| Endpoints | Sie werden unter /.well-known/openid-configuration der Issuer-URL gesucht. Kann ein IdP sie nicht finden, geben Sie die Adressen für authorization, token, JWKS und userinfo unter Erweiterte Einstellungen öffnen direkt ein. |
| Zeitlimit | 15 Sekunden pro Aufruf des IdP |
Die IdP-Anwendung muss client_secret_post zulassen. Ist nur client_secret_basic oder private_key_jwt erlaubt, schlägt der Token-Austausch fehl.
SAML 2.0
| Element | Verhalten |
|---|---|
| Anfrage | Sendet einen AuthnRequest über das HTTP-Redirect-Binding. Die Anfrage wird nicht signiert. |
| Inhalt der Anfrage | Destination=SSO-URL des IdP, AssertionConsumerServiceURL=ACS-URL, ProtocolBinding=HTTP-POST, Issuer=SP-EntityID, NameIDPolicy Format=…:nameid-format:unspecified, AllowCreate=true |
| Antwort | HTTP-POST-Binding mit SAMLResponse und RelayState. Der RelayState muss unverändert zurückgegeben werden. |
| Signatur | Response oder Assertion muss eine gültige Signatur tragen. Als Prüfschlüssel dient ausschließlich das am Bildschirm registrierte Zertifikat. |
| Assertion | Die Antwort muss genau eine Assertion enthalten. Verschlüsselte Assertions (EncryptedAssertion) werden nicht akzeptiert. |
| Status | StatusCode lautet urn:oasis:names:tc:SAML:2.0:status:Success |
| Issuer | Wenn Sie die EntityID des IdP angegeben haben, muss sie mit dem Issuer der Assertion übereinstimmen |
| Bedingungen | NotBefore und NotOnOrAfter (Toleranz 300 Sekunden), Audience=SP-EntityID |
| SubjectConfirmationData | Recipient=ACS-URL, NotOnOrAfter (Toleranz 300 Sekunden), InResponseTo=ID der von Keural gesendeten Anfrage |
Ein Attribut, dessen Name oder FriendlyName einer der folgenden Werte ist (ohne Beachtung der Groß-/Kleinschreibung): email, mail, emailAddress, E-Mail-Addresses, http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress. Fehlt es, wird die NameID mit @ verwendet. | |
| Name | displayName, name, cn, http://schemas.microsoft.com/identity/claims/displayname |
| Zertifikat | Ein X.509-Zertifikat. Im PEM- oder Base64-Format (DER). Zum Austausch geben Sie das neue Zertifikat ein und speichern es. |
| Metadaten | Statt die IdP-Metadaten-XML hochzuladen, geben Sie drei Werte ein: IdP-EntityID, IdP-SSO-URL und Zertifikat. |
Benutzerzuordnung
| Element | Verhalten |
|---|---|
| Kriterium für die Weiterleitung an SSO | Der Teil der E-Mail-Adresse nach @ entspricht genau einem Eintrag der Liste der E-Mail-Domains (ohne Beachtung der Groß-/Kleinschreibung). Subdomains werden separat registriert. |
| Kontosuche | Das Keural-Konto wird anhand der vom IdP gelieferten E-Mail-Adresse (in Kleinbuchstaben) gesucht. |
| Wenn kein Konto existiert | Ist Benutzer beim ersten Login automatisch anlegen (JIT) aktiviert, wird das Konto angelegt; bei deaktivierter Option wird die Anmeldung abgelehnt. |
| Aufnahme in die Organisation | Ist die Person kein Mitglied der Organisation, wird sie als Mitglied aufgenommen. Sind die Plätze belegt oder gehört das Konto zu einer anderen Organisation, erfolgt keine Aufnahme, und es wird nur die Anmeldung erlaubt. |
| Bedingung für das Speichern einer E-Mail-Domain | Per DNS-TXT verifizierte Domain, öffentliche E-Mail-Domains ausgenommen |
Domain-Verifizierung
| Element | Wert |
|---|---|
| Eintragstyp | TXT |
| Host | Die registrierte Domain unverändert (z. B. acme.com). Keine vorangestellte Subdomain verwenden. |
| Wert | keural-verify=<UUID>, genau so wie am Bildschirm angezeigt |
| Zeitpunkt der Prüfung | Wird einmal beim Klick auf Verifizierung bestätigen abgefragt. |
SCIM 2.0
| Element | Wert |
|---|---|
| Basis-URL | {API}/scim/v2 |
| Authentifizierung | Authorization: Bearer <SCIM-Token>. Das Token beginnt mit scim_ und wird nur einmal bei der Ausstellung angezeigt. |
| Content-Type | Anfrage application/scim+json oder application/json, Antwort application/scim+json |
| Statuscodes | Es werden die echten HTTP-Statuscodes zurückgegeben. Der Fehler-Body hat das SCIM-Error-Format (schemas, status, detail, scimType). |
Endpoints
| Methode | Pfad | Verhalten |
|---|---|---|
GET | /Users | Liste. filter=userName eq "…", startIndex (Standard 1), count (Standard 100, maximal 200) |
GET | /Users/{id} | Einen Benutzer abrufen |
POST | /Users | Anlegen (201). Existiert dieselbe E-Mail bereits, wird 409 zurückgegeben. |
PATCH | /Users/{id} | Ändert active, displayName, name.formatted, name.givenName |
PUT | /Users/{id} | Übernimmt displayName, name und active. Fehlt active, gilt der Benutzer als aktiv. |
DELETE | /Users/{id} | Sperrt das Konto (204). Die Daten werden nicht gelöscht. |
GET | /Groups, /Groups/{id} | Abruf der beiden festen Gruppen. filter=displayName eq "…" |
PATCH | /Groups/{id} | Mitglieder hinzufügen, entfernen oder ersetzen |
GET | /ServiceProviderConfig, /ResourceTypes, /Schemas | Abruf der unterstützten Funktionen |
Benutzerattribute
| Attribut | Verwendung |
|---|---|
userName | E-Mail. Fehlt sie, wird emails[0].value verwendet. |
displayName · name.formatted · name.givenName+name.familyName | Anzeigename |
active | false sperrt (blockiert die Anmeldung), true stellt wieder her |
id | Keural-Benutzer-ID. Sie wird in der Antwort zurückgegeben. |
externalId wird nicht gespeichert. Um einen Benutzer im IdP zu finden, verwenden Sie den Filter userName.
Gruppen
| id | displayName | Bei Hinzufügen eines Mitglieds | Bei Entfernen eines Mitglieds |
|---|---|---|---|
keural-admins | Keural Admins | Administrator | Mitglied |
keural-members | Keural Members | Mitglied | Keine Änderung |
Die Rolle des Organisationsinhabers wird durch SCIM nicht geändert. Das Anlegen und Löschen von Gruppen (POST·DELETE /Groups) gibt 501 zurück. Der value eines Gruppenmitglieds ist die Keural-Benutzer-ID (id aus /Users).
Unterstützungsumfang
| Funktion | Unterstützt |
|---|---|
| PATCH | Ja |
| Filter | userName eq, displayName eq |
| Bulk · Sortierung · ETag · Passwortänderung | Nein |
Fehler
| Status | scimType | Ursache |
|---|---|---|
400 | invalidValue | userName und emails fehlen beide |
401 | — | Token fehlt oder ist falsch, oder SCIM-Provisioning ist deaktiviert |
404 | — | Der Benutzer oder die Gruppe gehört nicht zu dieser Organisation |
409 | uniqueness | Ein Konto mit derselben E-Mail existiert bereits, oder die Platzzahl wurde überschritten |
501 | — | Anlegen oder Löschen von Gruppen |