Beskrivning av den specialisering inom standarderna SCIM och SS12000 som tagits fram för automatiserad kontoadministration i digitala läromedel och liknande system. Profilen beskriver vilka objekttyper som ska användas, vilka av objektens attribut som skall användas, hur autentisering mellan ändpunkter utförs och hur federationen är utformad.
Nedan följer det urval av tillgängliga objekttyper som finns beskrivna i SCIM core schema1 och i SS12000 extended schema2.
Samtliga objekt som skapas hos klienten för överföring till en server skall alltid ha attributet externalId som tilldelas sitt värde av klienten och som är av typen UUID (tex. 6561043b-c636-b247-8487-6561043bc636). När servern tar emot och lagrar objektet skall den alltid ge attributet id samma värde som externalId.
Valfria objekt och attribut innebär att huruvida dessa skall skickas eller inte avtalas mellan varje tjänsteleverantör och huvudman.
Ett objekt per skolhuvudman. Objektet innehåller endast organisationens namn och har inga attribut som refererar till andra objekt.
Eftersom klienten alltid kontaktar servern med sitt entityID vet servern redan att alla objekt från ett entityID tillhör samma organisation, därför kan objektet utelämnas.
| Attribut | Dataformat | Beskrivning | |
|---|---|---|---|
| displayName2 | String | Organisationens namn | Krävs |
Ett objekt som grupperar en eller flera skolenheter (SchoolUnit) till en "skola". T.ex har större skolor ofta flera rektorer och varje rektor ansvarar för ett rektorsområde eller motsvarande.
SchoolUnitGroup har inga attribut som refererar till andra objekt, inte ens en lista på vilka SchoolUnit som ingår.
| Attribut | Dataformat | Beskrivning | |
|---|---|---|---|
| displayName2 | String | Skolans namn | Krävs |
I Skolverkets organisationsmodell för skolan har varje skolenhet precis en rektor och varje skolenhet har en unik nationell 8-siffrig skolenhetskod. I verkligheten tänker man ofta på en skola som en byggnad eller flera byggnader som alla tillhör skolan, tex. "Centralskolan". Som elev eller vårdnadshavare känner man oftast inte till något om den organisatoriska uppdelningen i rektorsområden och skolenheter, utan man "går på Centralskolan".
En elev kan bara vara inskriven på en skolenhet.
En lärare kan undervisa på flera skolenheter.
| Attribut | Dataformat | Beskrivning | |
|---|---|---|---|
| displayName2 | String | Skolenhetens namn | Krävs |
| schoolUnitCode2 | String | SCB skolenhetskod | Krävs |
| organisation2 | REF Organisation | Organisationstillhörighet | Valfritt |
| schoolUnitGroup2 | REF SchoolUnitGroup | Skoltillhörighet | Valfritt |
| schoolTypes2 | Code_SchoolType | Skolform | Valfritt |
| municipalityCode2 | String | Kommunkod | Valfritt |
Ett abstrakt relationsobjekt som knyter en anställning till en person och en skolenhet. Varje person (User) som är anställd som lärare eller annan personal inom skolan skall ha ett Employmentobjekt. Om personen arbetar på mer än en skolenhet skall den ha ett Employment-objekt för varje skolenhet.
| Attribut | Dataformat | Beskrivning | |
|---|---|---|---|
| employedAt2 | REF SchoolUnit | Anställande enhet | Krävs |
| user2 | REF User | Anställd person | Krävs |
| employmentRole2 | Code_EmploymentRole | Befattning | Krävs |
| signature2 | String | Lärarsignatur | Valfritt |
Ett relationsobjekt som ytterst binder ihop en lärarperson (User) med elevgrupp eller elev. Genom attributet teachers.employment (TeacherAssignment) refererar Activity via noll eller flera Employment-objekt till lärarpersoner (User). Genom attributet GroupAssignment refereras till elevgrupper (StudentGroup).
För tjänster där relationen lärare - elev är betydelsefull för tjänstens funktionalitet är Activity-objektet av central betydelse.
| Attribut | Dataformat | Beskrivning | |
|---|---|---|---|
| displayName2 | String | Aktivitetens namn | Krävs |
| activityType2 | Code_ActivityType | Aktivitetstyp | Valfri |
| owner2 | REF SchoolUnit | Kopplad skolenhet | Krävs |
| teachers2 | REF Employment | Kopplad lärare | Krävs |
| groups2 | REF StudentGroup | Kopplad elevgrupp | Krävs |
| topic2 | REF Course/Subject | Kurs eller ämne | Valfri |
Specialiserat gruppobjekt som förutom attributet studentMemberships som refererar till gruppens medlemmar (User) även har attribut som refererar till den skolenhet (SchoolUnit) som elevgruppen tillhör och beskrivande attribut. StudentGroup används både för skolklasser och undervisningsgrupper.
| Attribut | Dataformat | Beskrivning | |
|---|---|---|---|
| displayName2 | String | Gruppens namn | Krävs |
| owner2 | REF SchoolUnit | Gruppens skoltillhörighet | Krävs |
| studentMemberships2 | REF User | Elev(er) i gruppen | Krävs |
| studentGroupType2 | Code_StudentGroupType | Typ av grupp | Valfritt |
Specialisering av User från SCIM core schema med ett antal extra attribut. Beskrivande attribut anpassade för svensk skola har lagts till, tex personnummer. Attributet enrolments innehåller elevinformation som årskurs (schoolYear), skolform (schoolType) mm. Attributet userRelations ger möjlighet att ange relation till ett annat User-objekt, tex vårdnadshavare (används inte i EGIL-profilen).
I grunden är User-objekten representationer av personer utan specificerad roll i organisationen. Rollen/rollerna bestäms genom relationsobjekt eller relationsattribut, tex kan en User ha ett Enrolment-attribut som anger att man är elev vid Vuxenutbildningen och samma User kan via kedjan Activity - TeacherAssignment - Employment vara lärare för en elevgrupp.
| Attribut | Dataformat | Beskrivning | |
|---|---|---|---|
| userName1 | String | Användarnamn* | Krävs |
| displayName1 | String | Förnamn Efternamn | Krävs |
| name.familyName1 | String | Efternamn | Krävs |
| name.givenName1 | String | Förnamn | Krävs |
| emails1 | String | e-postadress | Valfritt |
| studentGroups2 | REF StudentGroup | Medlemskap i elevgrupp | Krävs** |
| civicNo | String | Personnummer YYYYMMDDNNNN | Valfritt |
| enrolments2 | REF SchoolUnit | Inskriven vid skolenhet | Krävs** |
| enrolments.schoolYear2 | Int | Årskurs*** | Valfritt |
| enrolments.programCode2 | String | Studievägskod (Gy/Vux)**** | Valfritt |
| enrolments.schoolType2 | Code_schoolType | Skolform | Valfritt |
| userRelation2 | REF User | Relaterad person | Valfritt |
| userRelation.relationType2 | Code_RelationType | Typ av relation | Valfritt |
* Värdet ska ha samma format som eduPersonPrincipalName i Skolfederations attributprofil, dvs användarId@organisation.
** Krävs för elever, inte för personal
*** 0 - 10
Ett objekt som beskriver en kurs som är knuten till en aktivitet.
| Attribut | Dataformat | Beskrivning | |
|---|---|---|---|
| courseCode2 | String | Kurskod, exempelvis MATMAT01a | Krävs |
De dataformat som attributen kan ha inom EGIL-projektet är:
UUID : Unik identifierare för en post. Består av 32 hexadecimala tecken (0 - 9, a - f) grupperade enligt 83a44180-6573-554b-0291-83a441806573
String : Teckensträng av godtycklig längd som kan innehålla utskrivbara tecken enligt UTF8
Int : Heltal av godtycklig längd
Code_EmploymentRole : Datatyp med specificerat värdeförråd (fr SS 12000); Rektor, Lärare, Förskollärare, Övrig pedagogisk personal, Annan personal.
Code_SchoolType : Datatyp med specificerat värdeförråd; FS (förskola), FSK (förskoleklass), FTH (fritidshem), GR (grundskola), GRS (grundsärskola), SP (specialskola), SAM (sameskola), GY (gymnasieskola), GYS (gymnasiesärskola, VUX (vuxenutbildning), SUV (särskild utbildning för vuxna), YH (yrkeshögskola), FHS (folkhögskola), HS (högskola), AU (annan utbildning).
Code_RelationType : Datatyp med specificerat värdeförråd; Vårdnadshavare, Annan ansvarig vuxen.
Code_ActivityType : Datatyp med specificerat värdeförråd; Undervisning, Elevaktivitet, Läraraktivitet, Övrigt.
REF (objekttyp): Referens till annat objekt inom en SCIM-domän. Objektreferensen består alltid av:
- value (refererade objektets UUID)
- $ref (refererade objektets URI i serversidans system)
- display (endast vid GET, refererade objektets displayName, i förekommande fall)
I SS12000 beskrivs även objekttyperna Subject, CalendarEvent, Room, Resource, TeacherException, StudentException och StudentGroupException . I detta skede görs bedömningen att de inte är nödvändiga för att uppnå projektets syfte.
Objekttyperna SchoolUnit, Employment, Activity och StudentGroup samt relationsattributen Enrolment (User), TeacherAssignment (Activity), StudentAssignment (Activity), GroupAssignment (Activity), StudentMembership (StudentGroup) och UserRelation (User) har alla subattributen startDate och endDate. Dessa uppgifter är centrala vid överföring av skolschemainformation men används inte i EGIL-profilen eftersom överförda uppgifter alltid avspeglar aktuell situation.
En fungerande server-implementation behöver inte stödja allt från SCIM, inte ens allt som är obligatoriskt enligt SCIM. För att kunna ta emot data måste servern implementera POST (skapa), PUT (uppdatera) och DELETE (ta bort) för alla objektstyper.
GET (för att läsa objekt) måste inte implementeras, dock rekommenderas grundläggande stöd även för GET. Under normal drift läser klienten inte från servern. Om klient och server av någon anledning har hamnat ur synk, eller om man misstänker att så kan vara fallet, har klienten dock bättre möjligheter att "laga" integrationen om servern kan berätta vilka objekt som finns. Det räcker alltså att klienten kan hämta en lista över alla objekt (per objektstyp) och se vilka UUIDs servern har. Det är upp till server-implementationen om man vill använda paginering eller ej när alla objekt returneras. Stöd för filtrering och sortering behöver inte implementeras.
För de metoder som implementeras är det viktigt att returkoder används korrekt enligt SCIM-standarden. Fel kan tyda på att klient och server har hamnat ur synk, genom att tolka returkoderna har klienten möjlighet att i viss mån rätta till sådana problem.
Säker kommunikation mellan klienter och servrar implementeras genom TLS med ömsesidig autentisering enligt separat specifikation, https://github.com/kirei/scim-fed-auth/
Anslutningar från klienter som ej presenterar klientcertifikat skall nekas av servern.
För att en klient ska kunna skicka data till en server krävs följande:
- En certifikatutfärdare (kan göras in-house eller köpas in som tjänst - behöver ej vara betrodd av några operativsystem eller webbläsare)
- En privat och en publik nyckel, och ett klientcertifikat från denna utfärdare
- Metadata om utfärdaren och nyckelns fingeravtryck skall vara publicerat i Skolfederations metadataregister (se nedan)
- En HTTPS-klient som kan använda klientcertifikatet (i testsyfte kan förslagsvis curl användas). Klienten skall också verifiera att serverns certifikat är utfärdat av en av de certifikatutfärdare som den mottagande organisationen har listat i metadataregistret, och att certifikatets nyckel har rätt fingeravtryck.
- Ett avtal med den mottagande organisationen. I normalfallet ska den mottagande servern ha en lista över vilka organisationers data som skall importeras från skolfederations metadataregister, som sedan avgör vilka anslutningar som ska tillåtas.
All kommunikation skall skyddas av HTTPS med TLS version 1.2 eller senare, och endast chifferuppsättningar som resulterar framtida sekretesskydd (Perfect Forward Secrecy, PFS), t.ex. ECDHE/DHE, får användas.
Den metadata som krävs för att implementera detta koordineras och hanteras av Skolfederation. Det bör dock påpekas att metadata för EGIL hanteras separat från den metadata som används för t.ex. SAML, och att det inte finns något direkt beroende på Skolfederation.
Innehåll i metadata för varje organisation:
- Entitetens (organisationens) ID, t ex egil.kommunen.se
- Lista över betrodda certifikatutfärdare
- CA-certifikatet i sin helhet, i PEM-format
- Lista över klienter
- Namn
- Den publika nyckelns fingeravtryck
- Lista över servrar
- Namn
- URI
- Den publika nyckelns fingeravtryck
Mer information om metadataregistret, inklusive nyckel för att verifiera metadata finns här:
https://www.skolfederation.se/teknisk-information/kontosynk/tekniska-miljoer/
Det metadataregister som användes under PoC-fasen finns publicerat här: https://fedscim-poc.skolfederation.se/md/skolfederation-fedscim-0_1.json
Registret är i signerat JSON-format, som ska verifieras med hjälp av denna publika nyckel: https://fedscim-poc.skolfederation.se/jwks
Exempeldata för en organisation ser ut på följande vis: https://github.com/kirei/scim-fed-auth/blob/master/example.json