OpenVOOT-avklaringer

3.1.1   SCIM

VOOT benytter seg av datatyper fra SCIM (https://tools.ietf.org/html/rfc7643#section-2.3).

I tillegg defineres en spesiell datatype, translatable-string.

3.1.2   translatable-string

VOOT definerer denne datatypen, som er en lokalisert tekststreng. Verdien styres av request-parametere, og vil enten være et dataobjekt med samtlige oversettelser for attributtet, eller en tekststreng med en utvalgt oversettelse.

Dette benyttes typisk for å tilby oversettelser for attributter som displayName og description.

Dersom request inneholder ?translate=false, skal objekt returnere alle oversettelser i attributter med denne datatypen. Verdien er da et objekt:

{
    "en": "Organization",
    "nb": "Organisasjon"
}

Språkkode skal være et gyldig kortnavn i ISO639-1. Det ser ikke ut til å være krav om hvilke språk som skal støttes.

Det er uklart hvorvidt språkstøtte for objekter må være implementert konsistent (altså om oversettelser må være tilstede for samtlige språk på samtlige objekter).

Dersom query-parameteret ikke er tilstede, eller satt til true, skal feltene kun innholde en utvalgt oversettelse, som velges ut i fra request-header Accept-Language.

Det også uklart hvilket språk som skal velges i en del tilfeller:

• Hva skjer dersom man ikke har med Accept-Language-header?
• Hva skjer dersom ingen av språkene fra Accept-Language er tilgjengelige for et objekt? For description er det kanskje greit med en tom verdi, men det er værre for påkrevde felt som displayName.
• Skal man blande språk dersom oversettelser ikke er implementert konsistent? Er det m.a.o. greit å returnere norsk description og engelsk displayName i ett og samme objekt, dersom Accept-Language: en, no;q=0.8 og det mangler description på engelsk?
• Hvilket språk velges dersom man spør etter makrospråk (f.eks. no), mens flere medlemmer av makrospråket er implementert (f.eks. nb og nn)

3.2.1   group

Objekt som beskriver en enkeltgruppe.

Minimalt eksempel:

{
    "id": "8878ae43-965a-412a-87b5-38c398a76569",
    "displayName": "Project on group APIs"
}

id → string

En unik ID for gruppe-objektet. I eksempelet er dette en UUID, som også er det Dataporten benytter i sitt gruppe-API.

Kan være en vilkårlig streng, så i Cerebrum kunne vi benyttet f.eks. gruppens entity_id.

displayName → translatable-string

Navn eller beskrivelse av gruppen.

Vi har ikke navn eller beskrivelse med flere språk i Cerebrum. I tillegg vil ikke beskrivelse være unikt nok til å brukes som displayName. Her vil nok gruppenavnet være mest meningsbærende - men dette kan ikke ha oversettelser?

Her kan det tenkes at vi burde implementere displayName-støtte for grupper (typ. EntityNameWithLanguage, hvor f.eks. group_name benyttes for alle språk som ikke har satt et displayName).

I tillegg kan objektet inneholde en serie med «valgfrie» attributter:

Er attributter egentlig valgfrie? Eller bare kondisjonelle; altså at de kan/må returneres i enkelte tilfeller? Savner evt. informasjon om dette i protokoll-spesifikasjonen!

description → string, translatable-string?

Beskrivelse av gruppen, kan valgfritt være translatable-string?

Her kan vi f.eks. eksponere description uavhengig av språk, evt. implementere en description med språkstøtte.

type → string

Spesifikasjonen sier «a pointer to a group type», men gir voot:default som eksempel. Så her er vel verdien ID-en til et gitt group type-objekt?

notBefore → DateTime, ISO8601-string?

> «the group did not exist before this date».

Grupper med notBefore dagens dato regnes som ugyldige, og vil typisk ekskluderes i en del utlistinger i API-et.

Her kan vi velge å eksponere created_date fra Cerebrum.

notAfter → DateTime, ISO8601-string?

> «the group is deleted or not valid after this date.»

Grupper med notAfter dagens dato regnes som ugyldige, og vil typisk ekskluderes i en del utlistinger i API-et.

Her kan vi velge å eksponere expire_date fra Cerebrum.

public → boolean

> «a boolean flag indicating whether the existence of this group and the
> basic group information is publicly available. Users may search and
> use groups in setting access control, even if they are not member of a
> group.»

Gjør gruppen synlig i søk/oppslag for brukere som ikke er medlem. Uklart om brukere som ikke er autentisert i det hele tatt skal få se disse gruppene.

Vi har et konsept om synlighet i Cerebrum, men dette bør nok ikke benyttes, hverken til tilgangsstyring eller til noe som helst annet. Det er brukt noe ukonsistent.

Tilgangskontroll må vel implementeres i VOOT-apiet? Det fremstår som litt uklart hva bruksområdet til dette attributtet er, eller hva som skal styre hvorvidt en gruppe er public.

active → boolean

> «may be set to false to indicate that the group is currently inactive.
> It will cause the group to not show up on compact group lists.»

Ser ut til å være et hint til grensesnitt om hvorvidt gruppen kan brukes / skal vises. Inaktive grupper skal ekskluderes i en del utlistinger i API-et.

sourceID → string

> «is an identifier that refer to the authorative source defining this
> group. This is useful when the VOOT Provider is merging information
> from a lot of different systems and passes this information on to the
> clients.»

Ser ut til å være et attributt hvor man kan eksponere kildesystem e.l. for grupper. Et eksempel bruker: "sourceID": "voot:sources:uninett:fs"

Kan være interessant f.eks. hvis vi bygger automatiske kurs-grupper o.l. fra FS, eller hvis vi ender opp med å representere roller i nytt ERP-system som grupper. Kan også være interessant for f.eks. virtuelle affiliations-grupper.

membership → list<membership>

I enkelte endepunkt vil gruppe-objektet kunne inneholde en liste over medlemsskap.

Spesifikasjonen sier ikke noe om når dette skal være inkludert.

3.2.2   membership

Objekt som beskriver et gruppemedlemsskap.

Minimalt eksempel:

{}

Objektet kan være tomt, i så fall betyr dette simpelthen at bruker er et ordinært medlem av gruppen (rolle member).

Valgfrie attributter:

basic → string

Medlemsrolle. Hvis ikke oppgitt, betyr dette at medlemmet er ordinært medlem.

Må være en av:

• member
• admin
• owner

Det legges ingen føringer på hvilke tilganger admin eller owner tilordnes.

Det skaper litt problemer for oss at andre roller enn member ser ut til å implisitt bety at man også er member. I Cerebrum kan man nemlig bli tilordnet tilganger (være admin for en gruppe) uten å selv være medlem av gruppen. Det er også uklart om rollen owner implisitt betyr at man er admin.

displayName → translatable-string

> «A human readable description of the memership role.»

En forklaring på hva rollen innebærer. Her er det ikke klart hvorvidt displayName må være konsistent med rolletypen

• Må displayName for en gitt rolle være lik i alle medlemsskap i et og samme API?
• eller kan man benytte ulikt displayName på en gitt rolle: - i ulike gruppetyper? - i ulike grupper av samme type? - i ulike medlemsskap i en og samme gruppe?

active → boolean

> «may be set to false to indicate that the user is a passive member of
> the group»

Noe uklart hva dette skal bety. I videre klarifisering kan det se ut til at dette kan benyttes for tidligere medlemmer av en gitt gruppe, for å f.eks. implementere støtte for en slags uniform grace-periode i eksterne systemer.

Dette er et punkt som bør avklares nærmere hvis det skal taes i bruk.

notBefore → DateTime, ISO8601-string?

> «the group did not exist before this date.»

Fra dokumentasjon så skal dette feltet evt. bare speile gruppens notBefore-felt.

Usikker på om dette er riktig, eller om meningen her er å støtte notBefore/notAfter på medlemsskap, separat fra selve gruppen…

notAfter → DateTime, ISO8601-string?

> «the group is deleted or not valid after this date.»

Se notBefore.

may → ?

> «An object of permissions that a user may or may not have related to
> the group. In example a user may be allowed to edit, manage, invite or
> delete a group.»

Man kan altså tilordne tilganger til et medlemsskap. Dette attributtet ser ikke ut til å være definert i spesifikasjonen, men et eksempel gies:

"may": {
    "listMembers": true
}

userId → string

> «If the membership object is used stand alone, and there is no
> implicit relation to a given user, the user may be referred to by
> using this property.»

Identifikator for hvilken bruker medlemsskapet gjelder.

Det må nok inkuderes i enkelte tilfeller/endepunkter. I enkelte endepunkt er det ikke gitt hvilken bruker man ser medlemsskap for, så det kan være hensiktsmessig å inkludere dette i objektet.

Mistenker at dette feltet egentlig skulle vært brukt i endepunktet /groups/{groupid}/members, i stedet for å returnere et uspesifisert objekt.

Verdien av feltet bør nok være noe som kan dyttes inn som userid i f.eks. GET /user/{userid}/groups, men det er lite som definerer bruker-objekter i VOOT.

groupID → string

> «If the membership object is used stand alone, and there is no
> implicit relation to a given group, the group may be referred to by
> using this property.»

Se userid. Merk ulik casing her?

3.2.3   group type

Objekt som beskriver sett av grupper. En gruppe kan kun ha en gruppetype.

Minimalt eksempel:

{
    "id": "voot:adhoc",
    "displayName": "foo"
}

id → string

En unik ID for gruppetypen.

Burde vi bruke en registrert urn, f.eks. vår egen urn:mace:uio.no (urn:mace:uio.no:voot:group-type:example)

displayName → translatable-string

Navn eller beskrivelse av gruppetypen.

Objektet skal si noe om hvilket bruksområde en gitt gruppe har.

I følge beskrivelsen kan man også utvide «Group»-objekter med egne attributter. Da kan gruppetypen si noe om hvilke attributter man kan forvente å finne i gruppeobjektet.

Gruppetyper er ikke en del av spesifikasjon, men Dataporten definerer et par:

eduperson:orgunit

OU-er i Feide. Dataporten genererer allerede disse for oss, uklart om en eventuell VOOT-integrasjon med Dataporten betyr at vi må begynne å eksponere disse gruppene selv.

eduperson:org

Feide-organisasjon -- Dataporten genererer allerede disse for oss.

TODO: Her er det vel bare en enkeltgruppe for f.eks. UiO / et gitt Cerebrum-miljø.

voot:adhoc

Manuelle grupper som opprettes og vedlikeholdes i f.eks. Dataporten.

Her må vi tenke oss godt om før vi begynner å klassifisere gruppene våre inn i gruppetyper. Vi kan dele inn grupper i Cerebrum i typer etter flere kriterier:

• manuell vs. automatisk vs. virtuell (kun en av disse er ikke som de andre)?
• posix vs ikke-posix?
• basert på spreads / hvilke systemer gruppen finnes i?
• visibility?

Eksempel-gruppene taler for å f.eks. benytte:

• en felles gruppetype for manuelle og automatiske grupper.
• en gruppetype per implementasjon av virtuelle grupper (kurs, affiliations, kull, studieemne)

For å kunne gjøre dette bør vi nok ha på plass litt flere gruppetyper før vi kan benynne å tenke på dette.