EgilDoc

EGIL implementationsprofil

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.

Objekt och attribut

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.

Organisation2 (valfritt)

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

SchoolUnitGroup2 (valfritt)

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

SchoolUnit2 (obligatoriskt)

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

Employment2 (obligatoriskt)

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

Activity2 (obligatorisk)

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

StudentGroup2 (obligatorisk)

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

User1,2 (obligatorisk)

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 Programkod (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

**** https://www.skolverket.se/skolutveckling/anordna-och-administrera-utbildning/administrera-utbildning/koder-for-studievagar-yrkespaket-och-sprak

Course (valfritt)

Ett objekt som beskriver en kurs som är knuten till en aktivitet.

Attribut Dataformat Beskrivning  
courseCode2 String Kurskod, exempelvis MATMAT01a Krävs

Dataformat i attributen

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:

Övriga objekttyper i SS12000

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.

Objekt med tidsangivelser i attribut

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.

Obligatorisk delmängd av SCIM

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.

Autentisering mellan klient och server

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:

Transportskydd

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.

Federation och metadata

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:

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