diff --git a/docs/iam/scim.md b/docs/iam/scim.md index 1dba46c84..72ece9aec 100644 --- a/docs/iam/scim.md +++ b/docs/iam/scim.md @@ -1,339 +1,787 @@ --- -title: REST API & SCIM +title: SCIM API --- -Dokumentasjon av det foreslåtte [SCIM](https://tools.ietf.org/html/rfc7643)-grensesnittet som skal tilbys av IAM-implementeringer i den norske høyere utdanningssektoren. -Hovedbruksområdet for dette API-et er å tilgjengeligjøre henting av brukerdata via IntArk +**Versjon:** 4.0 +**Dato:** 4. februar 2026 +**Generasjon:** Felles IAM G4 -En funksjonell mock-up av dette API-et er tilgjengelig via [UiBs API Gateway](https://api-uib.intark.uh-it.no/#!/apis/91a73d99-d9b2-452a-a73d-99d9b2e52a9a/detail). +Dette dokumentet beskriver Felles IAM SCIM API-implementasjonen, inkludert LDAP-til-SCIM attributt-mappinger, API-responsstrukturer og eksterne avhengigheter. +Hovedbruksområdet for dette API-et er å tilgjengeligjøre henting av brukerdata via IntArk. -De standardiserte stiene for SCIM inkluderer; -* `/Users`: for administrasjon av brukerkontoer. -* `/Users/{id}`: For spesifikke brukerkontoer. -* `/Groups`: For administrasjon av grupper. -* `/Groups/{id}`: For spesifikke grupper. +APIet følger [SCIM 2.0-protokollen (RFC 7643/7644)](https://datatracker.ietf.org/doc/html/rfc7643) -(Vi bruker kun User-endepunktene akkurat nå) +Lenke til [Swagger fil](https://sikt-dev.eu001-rapididentity.com/api/rest/restpoints/Scim/v2/swagger.json) -## Personer vs brukerkontoer -SCIM er i utgangspunktet utformet som en REST-basert erstatning for LDAP. Som har de samme -tvertydlighetene når det gjelder hva brukerobjektene representerer. -Er de personer eller er de kontoer som tilhører personer(og andre enheter). +| Beskrivelse | Verdi | +|-------------|-------| +| Standard sidestørrelse | 100 | +| Maksimal sidestørrelse | 1000 | +| Content-Type | `application/scim+json` | -I denne sammenhengen erklærer vi dem som _kontoer_, og vi antyder at på et -senere tidspunkt kan utvide SCIM-implementeringen med _person_-objekter. -I denne modellen kan en person være eier av flere brukerkontoer. Vi vurderer -også en av disse kontoene som personens primære brukerkonto. Brukerobjektene -for primærbrukerkontoen vil ha en blanding av attributter som beskriver kontoen og attributter som beskriver personen. +## Innholdsfortegnelse -Man kan også ha kontoer som ikke tilhører personer. -Dette kan være kontoer som representerer enheter, applikasjoner eller andre systemer. +1. [Brukerressurs (/Users)](#brukerressurs) + - [Brukerobjektstruktur](#brukerobjektstruktur) + - [Brukerattributt-mappinger](#brukerattributt-mappinger) +2. [Grupperessurs (/Groups)](#grupperessurs) + - [Gruppeobjektstruktur](#gruppeobjektstruktur) + - [Gruppeattributt-mappinger](#gruppeattributt-mappinger) +3. [Attributt-transformasjoner](#attributt-transformasjoner) +4. [Eksterne avhengigheter](#eksterne-avhengigheter) +5. [Filteroperatorer](#filteroperatorer) +6. [Eksempler på API-kall](#eksempler-på-api-kall) +7. [SCIM-hendelser - Meldingskø](#scim-hendelser---meldingskø) +## Brukerressurs (/Users) -## Minimumskrav +### Brukerobjektstruktur -I denne seksjonen blir det definert hva som er minstekravnene til implementasjonen. +Brukerressursen returnerer følgende JSON-struktur: -* Implementere `/Users` Gir muligheten til å bla gjennom tilgjengelige kontoer. (En implementasjon kan velge kun å eksponere Feide-aktiverte kontoer). -* Implementere `/Users/{id}` Henter data for en spesifikk konto. -* Implementere `/Users?filter=userName eq "..."` Gjør det mulig å slå opp en bestemt konto. -* Implementere `/Users?userName=...` En mer praktisk ustandardistert versjon av det samme som over. -* Gjøre `/Groups` funksjonell, men det er greit at den bare returnerer `ListResponse`. -* Publisere meldinger på meldingskø når et brukerobjekt er Opprettet, Oppdatert eller Slettet. - -Følgende attributter bør være tilgjengelig på brukerobjektet. +```json +{ + "schemas": [ + "urn:ietf:params:scim:schemas:core:2.0:User", + "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User", + "no:edu:scim:user" + ], + "id": "UHID", + "externalId": "UHID", + "userName": "bruker@institusjon.no", + "displayName": "Visningsnavn", + "name": { + "formatted": "Fullt navn", + "familyName": "Etternavn", + "givenName": "Fornavn" + }, + "profileUrl": "https://...", + "title": "Stillingstittel", + "userType": "Employee|Student|External|Other", + "preferredLanguage": "no", + "active": true, + "emails": [ + { "value": "epost@institusjon.no", "type": "work" } + ], + "phoneNumbers": [ + { "value": "+47...", "type": "work" }, + { "value": "+47...", "type": "mobile" } + ], + "addresses": [ + { + "formatted": "Fullstendig adresse", + "streetAddress": "Gateadresse 1", + "locality": "By", + "postalCode": "0000", + "country": "Norway", + "type": "work" + } + ], + "roles": ["iam:employee", "iam:student"], + "groups": [ + { + "value": "gruppe-uuid", + "$ref": "https://.../Groups/gruppe-uuid", + "displayName": "Gruppenavn", + "type": "direct" + } + ], + "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": { + "employeeNumber": "12345678", + "costCenter": "0001", + "organization": "Organisasjonsnavn", + "division": "Avdeling", + "department": "Enhet", + "manager": { + "value": "Leders UHID", + "$ref": "https://.../Users/leder-uhid", + "displayName": "Ledernavn" + } + }, + "no:edu:scim:user": { + "employeeNumber": "12345678", + "studentNumber": "123456", + "fsPersonNumber": "12345", + "gregPersonNumber": "1234", + "eduPersonPrincipalName": "username@institusjon.no", + "userPrincipalName": "username@institusjon.no", + "accountType": "primary", + "primaryOrgUnit": { + "symbol": "AVD", + "legacyStedkode": "123456", + "nameNb": "Avdeling", + "nameEn": "Department" + }, + "orgUnits": [ + { + "symbol": "AVD", + "legacyStedkode": "123456", + "nameNb": "Avdeling", + "nameEn": "Department", + "type": "primary" + } + ] + }, + "meta": { + "resourceType": "User", + "created": "2024-01-15T10:30:00Z", + "lastModified": "2024-06-20T14:22:00Z", + "location": "https://.../Users/uhid" + } +} +``` -* `.id` -* `.meta` -* `.userName` -* `.active` -* `.displayName` -* `.name.formatted` -* `.name.givenName` -* `.name.familyName` - -* `.no:edu:scim:user:accountType` -* `.no:edu:scim:user:employeeNumber` -* `.no:edu:scim:user:eduPersonPrincipalName` -* `.no:edu:scim:user:userPrincipalName` +### Brukerattributt-mappinger + +#### Skjema for bruker (`urn:ietf:params:scim:schemas:core:2.0:User`) + +| SCIM-attributt | LDAP-attributt | Type | Transformasjon | Beskrivelse | +|----------------|----------------|------|----------------|-------------| +| `id` | `idautoId` | Streng | Ingen | Unik bruker-ID (UHID) | +| `externalId` | `idautoID` | Streng | Ingen | Unik bruker-ID (UHID) | +| `userName` | `idautoPersonSystem5ID` | Streng | Ingen | Brukerens innloggingsnavn (Feide ID) | +| `displayName` | `displayName` | Streng | Beregnet fra foretrukket navn | Visningsnavn for brukeren | +| `name.formatted` | `displayName` | Streng | Ingen | Formatert fullt navn | +| `name.familyName` | `sn` | Streng | Bruker `idautoPersonPreferredLastName` hvis tilgjengelig | Etternavn | +| `name.givenName` | `givenName` | Streng | Bruker `idautoPersonPreferredName` hvis tilgjengelig | Fornavn | +| `profileUrl` | `idautoPersonProfileUrl` | Streng | Ingen | URL til brukerprofil | +| `title` | `idautoPersonJobTitle` | Streng | Ingen | Stillingstittel | +| `userType` | `idautoPersonAffiliation` | Streng | [Se userType-transformasjon](#usertype-transformasjon) | Brukertype (Employee/Student/External/Other) | +| `preferredLanguage` | `idautoPersonPreferredLanguage` | Streng | Ingen | Foretrukket språk | +| `active` | `idautoDisabled` | Boolean | **Invertert**: LDAP `TRUE` → SCIM `false` | Om kontoen er aktiv | +| `emails[type=work].value` | `idautoPersonSystem2ID` | Streng | Ingen | Institusjonsepostadresse | +| `phoneNumbers[type=work].value` | `idautoPersonOfficePhone` | Streng | Ingen | Kontortelefon | +| `phoneNumbers[type=mobile].value` | `idautoPersonPhoneExtension` | Streng | Ingen | Jobbmobil | +| `addresses[type=work].formatted` | `idautoPersonWorkStreetAddress` | Streng | Parset | Fullstendig arbeidsadresse | +| `addresses[type=work].streetAddress` | `idautoPersonWorkStreetAddress` | Streng | Parset | Arbeidsadresse gateadresse | +| `addresses[type=work].locality` | `idautoPersonWorkCity` | Streng | Ingen | Arbeidsadresse by | +| `addresses[type=work].postalCode` | `idautoPersonWorkPostalCode` | Streng | Ingen | Arbeidsadresse postnummer | +| `addresses[type=work].country` | `idautoPersonWorkCountry` | Streng | Ingen | Arbeidsadresse land | +| `addresses[type=home].streetAddress` | `idautoPersonStreetAddress` | Streng | Ingen | Hjemmeadresse gateadresse | +| `addresses[type=home].locality` | `l` | Streng | Ingen | Hjemmeadresse by | +| `addresses[type=home].postalCode` | `postalCode` | Streng | Ingen | Hjemmeadresse postnummer | +| `roles` | `idautoPersonAppRoles10` | Array | Flerverdiet | Forretningsroller | +| `groups` | `memberOf` | Array | DN konverteres til SCIM-referanse | Gruppemedlemskap | +| `meta.created` | `createTimestamp` | DatoTid | LDAP→SCIM datoformat | Opprettelsestidspunkt i RI Portalen | +| `meta.lastModified` | `modifyTimestamp` | DatoTid | LDAP→SCIM datoformat | Sist endret tidspunkt i RI Portalen | + +#### Enterprise-brukerutvidelse (`urn:ietf:params:scim:schemas:extension:enterprise:2.0:User`) + +| SCIM-attributt | LDAP-attributt | Type | Transformasjon | Beskrivelse | +|----------------|----------------|------|----------------|-------------| +| `employeeNumber` | `idautoPersonPayrollID` | Streng | Ingen | Ansattnummer fra lønnssystem | +| `costCenter` | `idautoPersonCostCenter` | Streng | Ingen | Kostnadssenter | +| `organization` | `o` | Streng | Ingen | Organisasjonsnavn | +| `division` | `idautoPersonBusinessUnit` | Streng | Ingen | Avdeling | +| `department` | `ou` | Streng | Ingen | Enhet/seksjon | +| `manager` | `manager` | Objekt | DN konverteres til SCIM-referanse | Referanse til brukerens leder | + +#### Norsk utdanningsutvidelse (`no:edu:scim:user`) + +| SCIM-attributt | LDAP-attributt | Type | Transformasjon | Beskrivelse | +|----------------|----------------|------|----------------|-------------| +| `employeeNumber` | `idautoPersonPayrollID` | Streng | Ingen | Ansattnummer | +| `studentNumber` | `idautoPersonStuID` | Streng | Ingen | Studentnummer | +| `fsPersonNumber` | `idautoPersonSchoolID` | Streng | Ingen | FS-personløpenummer fra Felles Studentsystem | +| `gregPersonNumber` | `idautoPersonHRID` | Streng | Ingen | GREG-personnummer fra gjesteregistrering | +| `eduPersonPrincipalName` | `idautoPersonSystem5ID` | Streng | Ingen | Feide ID | +| `userPrincipalName` | Konfigurerbar | Streng | Standard: `idautoPersonSystem2ID`, fallback: `uid@inst_domain` | UPN hos institusjonen (AD) | +| `norEduPersonNIN` | `idautoPersonNationalID` | Streng | **Filtrert fra responser** (kun søk) | Fødselsnummer (kun søk, returneres ikke) | +| `accountType` | `idautoPersonAffiliations` | Streng | Beregnet: returnerer "primary" hvis gyldige tilknytninger | Kontotype | +| `primaryOrgUnit` | `idautoPersonDeptCode` | Objekt | Parset: `symbol\|nameNb\|nameEn\|legacyStedkode` | Primær organisasjonsenhet | +| `orgUnits` | `idautoPersonDeptCodes` | Array | Parset til array av OrgUnit-objekter | Liste over organisasjonsenheter | -## Meldinger (MQ) +--- -Oppdatering på brukerobjekt som er eksponsert i dette API-et varsles via meldinger til IntArk MQ og følger det foreslåtte [SCIM Event Extension](https://tools.ietf.org/html/draft-hunt-scim-notify-00) strukturen +## Grupperessurs (/Groups) -Siden IntArk foretrekker korte/mindre meldinger, så inkluderes ikke `.values` attributtet. +### Gruppeobjektstruktur -Disse hendelsene er kodet i JSON og ser slik ut: +Grupperessursen returnerer følgende JSON-struktur: ```json { - "schemas": ["urn:ietf:params:scim:schemas:notify:2.0:Event"], - "resourceUris": [ - "https://gw-uib.intark.uh-it.no/iga/scim/v2/Users/362ff2749bfb11eabbd5600308a4105a" + "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"], + "id": "uuid", + "externalId": "streng", + "displayName": "Gruppenavn", + "members": [ + { + "value": "bruker-uhid", + "$ref": "https://.../Users/bruker-uhid", + "displayName": "Brukernavn", + "type": "User" + } ], - "type":"MODIFY", - "attributes": ["emails", "name.givenName", "no:edu:scim:user:userPrincipalName"] + "meta": { + "resourceType": "Group", + "created": "2024-01-15T10:30:00Z", + "lastModified": "2024-06-20T14:22:00Z", + "location": "https://.../Groups/uuid" + } } ``` -Eksempel på emne er meldningen "no.uib.iga.scim.user.modify". - - -## Anbefalte funksjoner +### Gruppeattributt-mappinger -I denne seksjoner utvides det på minstekravene og definerer noen funksjoner som -kan være nyttige og som vi foretrekker all implementasjon til å vurdere. +| SCIM-attributt | LDAP-attributt | Type | Transformasjon | Beskrivelse | +|----------------|----------------|------|----------------|-------------| +| `id` | `idautoId` | Streng | Ingen | Unik gruppe-ID | +| `externalId` | `ubidExternalID` | Streng | Ingen | Ekstern identifikator | +| `displayName` | `cn` | Streng | Ingen | Gruppenavn | +| `members` | `member` | Array | DN konverteres til SCIM-referanse | Liste over gruppemedlemmer | +| `meta.created` | `createTimestamp` | DatoTid | LDAP→SCIM datoformat | Opprettelsestidspunkt | +| `meta.lastModified` | `modifyTimestamp` | DatoTid | LDAP→SCIM datoformat | -* Implementere `/Users?employeeNumber=...` -* Implementere `/Users?studentNumber=...` -* Implementere `/Users?fsPersonNumber=...` -* Implementere `/Users?norEduPersonNIN=...` -* Implementere funksjonell `/Groups` og `/Groups/{id}` som eksponerer de samme gruppene som er tilgjengelig i LDAP/AD -* Mer attributter på brukerobjektet, spesielt `.phoneNumbers` og `.enterprise.manager`. -* Søke opp brukere med navn og andre attributter. -* Implementere `/Persons` og `/Persons/{id}` endepunkter. Et skjema for personobjektet er ikke enda definert. +--- +## Attributt-transformasjoner -## feltnavn spesifikasjon +### userType-transformasjon -### User `.id` +LDAP-verdien `idautoPersonAffiliation` transformeres til standardiserte SCIM-verdier: -Dette bør helst være en UUID-lignende streng, -men tjenesten tillater også andre formater være `.id` -sånn som for eksempel `.username`. -Det bør være mulig å be om JSON-objektet som -representerer denne brukeren med en URL-sti på -`/Users/{id}`, der `{id}` erstattes med verdien av dette -feltet. +| SCIM userType | LDAP-verdier (ikke skille mellom store/små bokstaver) | +|---------------|--------------------------------------------------------| +| `Employee` | employee, faculty, staff, separated employee | +| `Student` | student, private candidate, leave of absence, separated student | +| `External` | long term guest, emeritus, visiting researcher, consultant | +| `Other` | Alle verdier som ikke matcher ovenfor | -### User `.meta` +### active-transformasjon -Standard SCIM meta informasjon på dette objektet. +`active`-attributtet utledes fra LDAP `idautoDisabled` med invertert logikk: -### User `.userName` +| LDAP idautoDisabled | SCIM active | +|---------------------|-------------| +| `TRUE` | `false` | +| Ikke satt / annet | `true` | -Formatet for brukernavnverdien skal være `{local-username}`. -SCIM tillater både bare brukernavn og brukernavn kvalifisert -med et domene. For å være konsistent returnerer vi alltid -fullt kvalisfisert navn. +### DN-referanseoppslag -Dette attributet er unikt, slik at ingen andre brukerobjekter -vil ha samme `.userName`. +Attributter som inneholder LDAP Distinguished Names (`memberOf`, `member`, `manager`) konverteres til SCIM-referanser: -`{local-username}` må matche regulært uttrykksmønster -`/[a-z][a-z0-9]{0,11}/`, og det fulle navnet vil kun -inneholde små bokstaver. +```json +{ + "value": "uhid", + "$ref": "https://base-url/ResourceType/uhid", + "displayName": "Navn fra displayName/cn", + "type": "direct|User" +} +``` -eksempel `gaa041@uib.no` +### Datoformat-konvertering -### User `.displayName` +LDAP-tidsstempler konverteres fra `yyyyMMddHHmmssZ`-format til ISO 8601 (`2024-01-15T10:30:00Z`). -For hovedbrukeren er dette det samme som `.name.formatted`. -For andre brukere kan dette være en hvilken som helst -streng som er passende for å definere hensikten for -denne brukeren. +### displayName-beregning -### User `.name` +`displayName` beregnes ved å bruke foretrukne navnefelt hvis tilgjengelig: +- Bruker `idautoPersonPreferredName` i stedet for `givenName` hvis tilstede +- Bruker `idautoPersonPreferredLastName` i stedet for `sn` hvis tilstede +- Format: `{fornavn} {etternavn}` -Dette er navnet på eieren av denne brukeren. Dette -attributtet er hovedsaklig for hovedbrukere. +### OrgUnit-parsing -Eksempel verdi: +Attributtene `primaryOrgUnit` og `orgUnits` parser LDAP-verdiformatet: +``` +symbol|nameNb|nameEn|legacyStedkode +``` +Til strukturerte objekter: ```json { - "formatted": "Gisle Aas", - "familyName": "Aas", - "givenName": "Gisle" + "symbol": "ACRONYM", + "nameNb": "Avdeling for teknologi", + "nameEn": "Department of Technology", + "legacyStedkode": "123456", + "type": "primary" } ``` -Disse attributtene skal bli latinifiserte versjoner av -det samme navnet på personen. -Hvis de er forskjellig, vil det orginale navnet for personen -ble presentert av ikke-standariserte attributter -`nativeFormatted`, `nativeFamilyName`, `nativeGivenName`. +--- -### User `.active` +## Eksterne avhengigheter -En boolsk verdi som bli satt til verdien `false` for -brukere som skal bli deaktivert. -Brukere skal ikke få muligheten til å logge inn på denne -brukerkontoen. Alle aktive sesjoner til denne -brukerkontoen skal også bli terminert. +### Globale variabler -### User `.externalId` +Disse variablene må konfigureres i RapidIdentity Connect-miljøet: -Identifikatoren til personen som eier denne kontoen. Det er å foretrekke at -`/Persons/{externalId}` henter informasjon om personen. For UH-IAM dette -feltet vil være UH-ID (en personorientert UUID-verdi). +| Variabel | Beskrivelse | Eksempel | +|----------|-------------|----------| +| `Global.SCIMBaseUrl` | Basis-URL for SCIM API | `https://gw-INST.intark.uh-it.no/scim/v2/` | +| `Global.inst_domain` | Institusjonsdomene | `inst.no` | +| `Global.SCIMVersion` | API-versjonsstreng | `v4.0.0` | +| `Global.SCIMDebug` | Aktiver feilsøkingslogging | `false` | +| `Global.scimUpnLdapMapping` | LDAP-attr for UPN | `idautoPersonSystem5ID` | +| `Global.employeeAffiliations` | Ansatt-tilknytningsverdier | `Administrative Staff,Faculty,...` | +| `Global.studentAffiliations` | Student-tilknytningsverdier | `Student,Bachelor,Master,...` | +| `Global.guestAffiliations` | Gjest-tilknytningsverdier | `External,Long Term Guest,...` | +| `Global.disabledAffiliations` | Deaktiverte konto-tilknytninger | `Separated Employee,Deceased,...` | +| `Global.shortTermGuestAffiliations` | Korttidsgjest-tilknytninger | `Short-Term Guest` | +| `Global.DisableMQ` | Deaktiver meldingskø | `true` | -### User `.emails` +### Standardkonfigurasjon (alle institusjoner) -E-postadresser som er tilknyttet denne brukerkontoen. -Disse typen e-postadresser er merket med et -type felt. Taggen "work" er brukt for disse e-postadressene -som er hovede-postadressen, dette gjelder også for studenter. +| Variabel | Verdi | +|----------|-------| +| `Global.metaLdapChangeLogDN` | `o=changelog` | +| `Global.metaEmployeeBaseDN` | `ou=Accounts,dc=meta` | +| `Global.scimChangeCookie` | `/cookies/scimChange.cookie` | -Eksempel på verdier: +### Eksterne actionsets +Disse actionsets kalles men er ikke inkludert i SCIM-prosjektet: -```json -[ - { "type": "work", "value": "Gisle.Aas@uib.no" }, - { "type": "internal", "value": "gaa041@uib.no" }, - { "type": "vanity", "value": "gisle@uib.no" } -] +| Actionset | Formål | +|-----------|--------| +| `FnToArray` | Hjelpefunksjon for å sikre at verdi er en array | +| `ErrorHandler` | Standard feilhåndterings-actionset | +| `Connection_MQAPI` | Meldingskø API-tilkobling (for endringshendelser) | + +### JavaScript-avhengigheter + +Ligger i Scim prosjektet under 'Files': + +| Fil | Formål | +|-----|--------| +| `nearley.js` | Earley-parserbibliotek for SCIM-filterparsing | +| `scimfilter.js` | SCIM-filtergrammatikkdefinisjon | + +--- + +## Filteroperatorer + +### Støttede SCIM-filteroperatorer + +| Operator | Beskrivelse | Eksempel | LDAP-oversettelse | +|----------|-------------|----------|-------------------| +| `eq` | Er lik | `userName eq "bruker@inst.no"` | `(attr=verdi)` | +| `ne` | Er ikke lik | `userType ne "Other"` | `(!(attr=verdi))` | +| `co` | Inneholder | `displayName co "Hansen"` | `(attr=*verdi*)` | +| `sw` | Starter med | `userName sw "ola"` | `(attr=verdi*)` | +| `ew` | Slutter med | `emails.value ew "@inst.no"` | `(attr=*verdi)` | +| `gt` | Større enn | `meta.created gt "2024-01-01"` | `(&(attr>=verdi)(!(attr=verdi)))` | +| `lt` | Mindre enn | `meta.lastModified lt "2024-06-01"` | `(&(attr<=verdi)(!(attr=verdi)))` | +| `ge` | Større eller lik | `meta.created ge "2024-01-01"` | `(attr>=verdi)` | +| `le` | Mindre eller lik | `meta.created le "2024-12-31"` | `(attr<=verdi)` | +| `pr` | Finnes | `title pr` | `(attr=*)` | +| `and` | Logisk OG | `active eq true and userType eq "Employee"` | `(&filter1 filter2)` | +| `or` | Logisk ELLER | `userType eq "Employee" or userType eq "Student"` | `(\|filter1 filter2)` | +| `not` | Logisk IKKE | `not(userType eq "Other")` | `(!filter)` | + +### Ikke-støttede funksjoner + +- **valuePath-uttrykk**: f.eks. `emails[type eq "work" and value co "@example.com"]` +- **eq null**: Null-likhetssammenligninger +- **Filter på name.formatted**: Ikke filtrerbart + +--- + +## Eksempler på API-kall + +### Tilgjengelige spørringsparametere + +API-et støtter følgende spørringsparametere som automatisk konverteres til SCIM-filteruttrykk: + +| Parameter | Beskrivelse | Konvertert filter | +|-----------|-------------|-------------------| +| `userName` | Brukernavn (legger automatisk til institusjonsdomene) | `filter=userName eq "verdi@institusjon.no"` | +| `employeeNumber` | Ansattnummer | `filter=no:edu:scim:user:employeeNumber eq "verdi"` | +| `userType` | Brukertype | `filter=userType eq "verdi"` | +| `active` | Aktiv status | `filter=active eq "verdi"` | +| `studentNumber` | Studentnummer | `filter=no:edu:scim:user:studentNumber eq "verdi"` | +| `fsPersonNumber` | FS-personnummer | `filter=no:edu:scim:user:fsPersonNumber eq "verdi"` | +| `gregPersonNumber` | GREG-personnummer | `filter=no:edu:scim:user:gregPersonNumber eq "verdi"` | +| `norEduPersonNIN` | Fødselsnummer (kun søk, returneres ikke i respons) | `filter=no:edu:scim:user:norEduPersonNIN eq "verdi"` | + +### Eksempler på bruk + +#### Hent alle aktive brukere + +```http +GET /scim/v2/Users?active=true ``` -### User `.phoneNumbers` +**Respons:** Alle brukere hvor `active` er `true`. -Telefonnummer som er offentlig og som er tilknyttet til denne brukeren. Telefonnummrene -er markert med en taggen "work", på de telefonnumrene som er foretrukken kontaktinformasjon. -Taggen "mobile" kan brukes når telefonnummer ikke er den foretrukne kontaktinformasjonen. -Taggen "secure" er telefon som egnder seg for 2 trinnsverifisering via SMS. +--- -Telefonnummrene er representert i full internasjonalt format prefikset med -"+" og uten mellomrom eller bindestreker. +#### Hent alle inaktive brukere -Eksempel på verdier: +```http +GET /scim/v2/Users?active=false +``` -```json -[ - { "type": "work", "value": "+4793241450" }, - { "type": "secure", "value": "+4793241450" }, - { "type": "mobile", "value": "+4793241450" } -] +**Respons:** Alle brukere som er deaktivert i systemet. + +--- + +#### Hent bruker med brukernavn + +```http +GET /scim/v2/Users?userName=ola.nordmann +``` + +**Merk:** Institusjonsdomenet legges automatisk til, så dette blir: `filter=userName eq "ola.nordmann@institusjon.no"` + +--- + +#### Hent bruker med fullt brukernavn + +```http +GET /scim/v2/Users?userName=ola.nordmann@inst.no +``` + +**Merk:** Hvis domene allerede er inkludert, brukes det direkte. + +--- + +#### Hent alle ansatte + +```http +GET /scim/v2/Users?userType=Employee +``` + +**Respons:** Alle brukere med `userType` lik "Employee". + +--- + +#### Hent alle studenter + +```http +GET /scim/v2/Users?userType=Student +``` + +**Respons:** Alle brukere med `userType` lik "Student". + +--- + +#### Hent alle eksterne brukere + +```http +GET /scim/v2/Users?userType=External +``` + +**Respons:** Alle gjester og eksterne brukere. + +--- + +#### Hent bruker med ansattnummer + +```http +GET /scim/v2/Users?employeeNumber=12345678 +``` + +**Respons:** Brukeren med det spesifikke ansattnummeret. + +--- + +#### Hent bruker med studentnummer + +```http +GET /scim/v2/Users?studentNumber=234567 +``` + +**Respons:** Studenten med det spesifikke studentnummeret. + +--- + +#### Hent bruker med FS-personløpenummer + +```http +GET /scim/v2/Users?fsPersonNumber=FS12345 +``` + +**Respons:** Brukeren med det spesifikke FS-personnummeret fra Felles Studentsystem. + +--- + +#### Hent bruker med GREG-personnummer + +```http +GET /scim/v2/Users?gregPersonNumber=GREG789 +``` + +**Respons:** Brukeren med det spesifikke GREG-personnummeret (gjesteregistrering). + +--- + +#### Søk etter bruker med fødselsnummer + +```http +GET /scim/v2/Users?norEduPersonNIN=12345678901 +``` + +**Merk:** Fødselsnummeret kan brukes til søk, men returneres **IKKE** i responsen av personvernhensyn. + +--- + +### Bruk av standard SCIM-filter + +For mer avanserte søk kan du bruke `filter`-parameteren med SCIM-filtersyntaks: + +#### Hent aktive ansatte + +```http +GET /scim/v2/Users?filter=active%20eq%20true%20and%20userType%20eq%20%22Employee%22 +``` + +**Dekodet:** `filter=active eq true and userType eq "Employee"` + +**Beskrivelse:** Finner alle brukere som er aktive og har brukertype "Employee". + +--- + +#### Hent ansatte eller studenter + +```http +GET /scim/v2/Users?filter=userType%20eq%20%22Employee%22%20or%20userType%20eq%20%22Student%22 +``` + +**Dekodet:** `filter=userType eq "Employee" or userType eq "Student"` + +**Beskrivelse:** Finner alle brukere som enten er ansatte eller studenter. + +--- + +### Filtrering med tekstoperatorer + +Disse eksemplene viser hvordan du kan bruke `co` (inneholder), `sw` (starter med) og `ew` (slutter med) for tekstsøk. + +#### Hent brukere med navn som inneholder "Hansen" + +```http +GET /scim/v2/Users?filter=displayName%20co%20%22Hansen%22 +``` + +**Dekodet:** `filter=displayName co "Hansen"` + +**Beskrivelse:** Finner alle brukere med "Hansen" i visningsnavnet (f.eks. "Hansen", "Berg Hansen", "Hansenberg"). + +--- + +#### Søk etter brukere med navn som inneholder tekst + +```http +GET /scim/v2/Users?filter=name.familyName%20co%20%22Berg%22 +``` + +**Dekodet:** `filter=name.familyName co "Berg"` + +**Beskrivelse:** Finner alle brukere med "Berg" i etternavnet (f.eks. "Bergersen", "Lindberg", "Berg"). + +--- + +#### Hent alle brukere med e-post fra et spesifikt domene + +```http +GET /scim/v2/Users?filter=userName%20ew%20%22%40inst.no%22 +``` + +**Dekodet:** `filter=userName ew "@inst.no"` + +**Beskrivelse:** Finner alle brukere hvor brukernavnet slutter med `@inst.no`. Nyttig for å filtrere brukere basert på institusjonstilhørighet. + +--- + +#### Hent brukere med brukernavn som starter med en bokstav + +```http +GET /scim/v2/Users?filter=userName%20sw%20%22a%22 +``` + +**Dekodet:** `filter=userName sw "a"` + +**Beskrivelse:** Finner alle brukere hvor brukernavnet starter med bokstaven "a". + +--- + +#### Søk etter brukere i en spesifikk avdeling + +```http +GET /scim/v2/Users?filter=urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:department%20co%20%22IT%22 ``` -### User `.profileUrl` +**Dekodet:** `filter=urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:department co "IT"` -URL for universitetets nettside for eieren av denne brukeren. +**Beskrivelse:** Finner alle brukere i avdelinger som inneholder "IT" i navnet (f.eks. "IT-avdelingen", "Seksjon for IT-drift"). - +#### Hent brukere opprettet etter en dato -### User `.roles` +```http +GET /scim/v2/Users?filter=meta.created%20ge%20%222024-01-01T00:00:00Z%22 +``` -Liste av forretningsroller(business roles) som er tilknyttet -brukeren. Man bruker taggene "staff", "guest" eller "student" -når det er passende. Denne listen av roller vil muligens bli større -med tiden. Universiteter kan introdusere private roller ved å -prefikse de med deres omvendte domenenavn, for eksempel "no.uib.breiflabb". +**Dekodet:** `filter=meta.created ge "2024-01-01T00:00:00Z"` -### User `.no:edu:scim:user` +**Beskrivelse:** Finner alle brukere som ble opprettet 1. januar 2024 eller senere. Bruk ISO 8601-format for datoer. -Dette attributtet inneholder objeket der vi utvider brukerobjektet med -felt som er spesifikke for det norsk UH-domenet. Strengen er også navnet -på et skjema og bør også finnes i `.schemas`-attributtet. +--- -### User `.no:edu:scim:user.accountType` +#### Kombinere tekstoperatorer med andre filtre -Beskriver hva slags brukerkonto dette er. +```http +GET /scim/v2/Users?filter=userName%20ew%20%22%40inst.no%22%20and%20active%20eq%20true%20and%20userType%20eq%20%22Employee%22 +``` -* Verdien er "primary" for primærkontoen til en person. -Hver person kan kun ha en primærkonto. +**Dekodet:** `filter=userName ew "@inst.no" and active eq true and userType eq "Employee"` -* Verdien "admin" Kontoer som brukes til privilegert tilgang og andre administrative formål. +**Beskrivelse:** Finner alle aktive ansatte med institusjonens e-postdomene. -* Verdien "test" Kontoer som kun brukes til testing. +--- -* Verdien "rpa" Kontoer som brukes av automatiseringsskript. +### Tekstoperator-referanse -### User `.no:edu:scim:user.employeeNumber` +| Operator | Navn | Eksempel | Matcher | +|----------|------|----------|---------| +| `co` | Inneholder | `displayName co "Berg"` | "Bergersen", "Lindberg", "Berg" | +| `sw` | Starter med | `userName sw "ola"` | "ola.nordmann", "olav.hansen" | +| `ew` | Slutter med | `userName ew "@inst.no"` | "bruker@inst.no", "test@inst.no" | -Dette er DFØ ID-en for ansatte som eier denne brukerkontoen. -Den er kun tilstede for primærkontoer. +--- -### User `.no:edu:scim:user.studentNumber` +### Paginering -Detter er studentnummeret for personen som eier denne brukerkontoen. -Den er kun tilstede for primærkontoer. +#### Hent første side med 50 resultater -### User `.no:edu:scim:user.fsPersonNumber` +```http +GET /scim/v2/Users?count=50 +``` -Dette er personløpenummer(FS ID) for personen som eier denne kontoen. -Dette felteet er kun tilstede for primærkontoer. +--- -### User `.no:edu:scim:user.norEduPersonNIN` +#### Hent side 2 (resultater 51-100) -Dette er norsk fødselsnummer for personen som eier denne brukerkontoen. -Identifikatoren kan være en ekte NIN, et D-nummer eller S-nummer. -Dette felter er kun tilstede for primærkontoer. +```http +GET /scim/v2/Users?startIndex=51&count=50 +``` -Denne attributtverdien er noe konfidensiell og bør kun gis til klienter med -særlige grunner til å kreve dette. +--- -### User `.no:edu:scim:user.eduPersonPrincipalName` +#### Kombinere paginering med filter -Feide-ID av denne brukerkontoen er spesifisert i dette feltet. -Dette feltet er kun tilstede for brukere som ikke er tilgjengelig gjennom Feide. +```http +GET /scim/v2/Users?active=true&startIndex=1&count=100 +``` -Det vil være den samme verdien som `eduPersonPrincipalName` attributtet -i LDAP og spesifisert [norEdu\*](https://docs.feide.no/reference/schema/attributes/edupersonprincipalname.html#saml-attribute-edupersonprincipalname). +--- -Eksempel på verdi: `gaa041@uib.no` +### Attributtseleksjon -### User `.no:edu:scim:user.userPrincipalName` +#### Hent kun spesifikke attributter -Dette er innlogginsnavnet til Microsoft login. -Dette er det samme som attributtet `userPrincipalName` i AD og Azure AD. +```http +GET /scim/v2/Users?attributes=userName,displayName,emails +``` - +**Respons:** Returnerer kun `userName`, `displayName` og `emails` for hver bruker. -Eksempel på verdi: `Gisle.Aas@uib.no` +--- -### User `.enterprise` +#### Ekskluder attributter -Dette er standard SCIM-bedriftsutvidelsesobjekt. -Det virkelige fulle navnet på dette attributtet er `urn:ietf:params:scim:schemas:extension:enterprise:2.0:User` -men vi forkortet referanser til det i denne beskrivelsen til `.enterprise`. Ledningsprotokollen -vil bruke hele navnet. +```http +GET /scim/v2/Users?excludedAttributes=groups,roles +``` -Det er ikke nødvendig med implementeringer for å gi denne utvidelsen. +**Respons:** Returnerer alle attributter unntatt `groups` og `roles`. -### User `.enterprise.employeeNumber` +--- -Dette er DFØ ID for den ansatte som eier denne kontoen. -Hvis begge er tilstede, skal denne ha samme verdi som `.no:edu:scim:user.employeeNumber`. +### Gruppeforespørsler -### User `.enterprise.costCenter` +#### Hent alle grupper -Dette er kontonummeret som brukes for utgifter knyttet til eieren av denne kontoen. -Ikke sikker på om dette er nyttig. +```http +GET /scim/v2/Groups +``` -### User `.enterprise.organization` +--- -Det norske navnet på organisasjoner som eieren av denne brukeren tilhører. -For ansatte og studenter vil dette være det samme navnet som på Skolen. -For gjester kan dette være navnet på organisasjonen de kommer fra. +#### Hent en spesifikk gruppe -### User `.enterprise.division` +```http +GET /scim/v2/Groups/550e8400-e29b-41d4-a716-446655440000 +``` -Det norske navnet på primærfakultetet som eieren av denne kontoen tilhører. +--- - +```http +GET /scim/v2/Groups?filter=displayName eq "IT-Avdeling" +``` -### User `.enterprise.manager` +--- + +#### Hent grupper med medlemmer + +```http +GET /scim/v2/Groups?attributes=displayName,members +``` + +--- + +### Enkeltbruker-forespørsler + +#### Hent en spesifikk bruker med UHID + +```http +GET /scim/v2/Users/550e8400-e29b-41d4-a716-446655440000 +``` + +## SCIM-hendelser - Meldingskø + +SCIM API-et kan publisere endringsmeldinger til en meldingskø når brukere opprettes, endres eller slettes. Institusjonen er selv ansvarlig for å sette opp og konfigurere meldingskøen som SCIM-systemet skal publisere til. + +Implementasjonen følger [SCIM Notify-standarden](https://datatracker.ietf.org/doc/html/draft-hunt-scim-notify-00) -For primære kontoer er dette satt til å referere til den primære brukerkontoen til lederen til personen som eier denne kontoen. -Alle ikke-primære kontoer bør sette dette til å referere til hovedkontoen til eieren. +### Hendelsestyper -Ytterligere informasjon om administratoren kan fås fra `/Users/{enterprise.manager.id}`. -`.enterprise.manager.displayName` er bare en kopi av `.displayName` til selve managerkontoen. +| Type | Beskrivelse | +|------|-------------| +| `ADD` | Ny bruker opprettet | +| `MODIFY` | Brukerattributter endret | +| `DELETE` | Bruker slettet | +| `ACTIVATE` | Brukerkonto aktivert | +| `DEACTIVATE` | Brukerkonto deaktivert | -Eksempel på verdi: +### Meldingsformat + +Meldinger publiseres til emnet (topic): `no.{inst}.iga.scim.user.{hendelsestype}` + +inst er basert på Global variabelen `Global.SCIMBaseUrl` + +Eksempel på emne er meldningen "no.uib.iga.scim.user.modify". + +Eksempel på meldingsstruktur: ```json { - "id": "452ff2749bfb11eabbd5600308a4105a", - "displayName": "Nina Kaurel" + "schemas": ["urn:ietf:params:scim:schemas:notify:2.0:Event"], + "type": "MODIFY", + "time": "2026-02-05T10:30:00Z", + "resourceUris": [ + "https://gw-inst.intark.uh-it.no/scim/v2/Users/uhid-12345" + ], + "attributes": [ + "displayName", + "name.givenName", + "emails[type eq \"work\"]", + "phoneNumbers[type eq \"work\"]" + ] } ``` +Siden IntArk foretrekker korte/mindre meldinger, så inkluderes ikke `.values` attributtet. + +**Felter:** +- `schemas`: SCIM Event-skjema +- `type`: Hendelsestype (ADD/MODIFY/DELETE/ACTIVATE/DEACTIVATE) +- `time`: Tidspunkt for hendelsen (ISO 8601) +- `resourceUris`: URI til den påvirkede ressursen +- `attributes`: Liste over attributter som ble endret (kun for MODIFY) + +---