SCIM-referanse

Utleggsappen implementerer SCIM 2.0 for automatisk brukerprovisjonering fra eksterne identitetsleverandører (Entra ID, Okta, Google Workspace, JumpCloud m.fl.).

1. Endpoint

https://api.utlegg.app/organizations/{organization_handle}/scim

organization_handle finner du ved å logge inn på dashbordet på https://utlegg.app og inspisere URL-en — du ser den som https://utlegg.app/{organization_handle}.

Tilgjengelige underressurser

/ServiceProviderConfig
/Schemas
/ResourceTypes
/Users
/Users/{id}

2. Autentisering

Bruk en Personal Access Token (PAT) i Authorization-headeren:

Authorization: Bearer ua_...

Hent en PAT ved å følge instruksjonene i API-dokumentasjonen — eller se API og autentisering → PAT.

Brukeren som eier PAT-en må ha admin-rolle i organisasjonen for at SCIM-kall skal autoriseres.

3. ResourceTypes

Vi støtter /Users. /Groups støttes ikke for øyeblikket.

4. Schema

Vi tilbyr et /Schemas-endepunkt, men autodiscover i Entra ID fungerer kun for godkjente / publiserte SCIM-applikasjoner. Vi tilfredsstiller alle krav for å bli dette, men grunnet Microsoft sitt Secure Future Initiative (SFI) har de pauset alle godkjenninger på ubestemt tid — det er derfor uklart når vi blir publisert.

Bruk derfor oversikten under for manuell mapping i IdP-en din.

Core schema

urn:ietf:params:scim:schemas:core:2.0:User

Attributt	Type	Notater
`userName`	string	required — brukes som e-post
`active`	boolean
`name.givenName`	string
`name.familyName`	string
`addresses[type eq "work"].streetAddress`	string
`addresses[type eq "work"].region`	string
`addresses[type eq "work"].postalCode`	string
`phoneNumbers[type eq "mobile"].value`	string	Lagres og returneres i E.164-format (f.eks. `+4799999999`).
`roles[primary eq "True"].value`	enum	`User` eller `Admin`

Enterprise extension

urn:ietf:params:scim:schemas:extension:enterprise:2.0:User

Attributt	Type	Notater
`department`	string	Format: `[departmentCode] [departmentName]` — f.eks. `"42 Engineering"`. Avdeling matches på `departmentCode`; eksisterende avdelinger (inkl. soft-slettede) gjenopprettes heller enn at det opprettes duplikat. Oppretter ny avdeling hvis koden ikke finnes.
`employeeNumber`	string	Maks 20 tegn, tegnsett `[a-zA-Z0-9-]`.
`manager.value`	string	SCIM-ID til leder. Leder må tilhøre samme organisasjon — en ID fra en annen org gir 404.

ServiceProviderConfig

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:ServiceProviderConfig"],
  "patch": { "supported": true },
  "bulk": { "supported": false },
  "filter": { "supported": true, "maxResults": 50 },
  "changePassword": { "supported": false },
  "sort": { "supported": true },
  "etag": { "supported": true }
}

Filtre (RFC 7644)

Støttet filteroperator: eq. Andre operatorer returnerer 400 Bad Request. Maks 50 resultater per spørring.

GET /Users?filter=userName eq "kari@example.com"
GET /Users?filter=active eq true
GET /Users?filter=phoneNumbers[type eq "mobile"].value eq "+4799999999"

Paginering

GET /Users støtter sideinndeling via to valgfrie URL-parametre:

Parameter	Type	Standard	Beskrivelse
`startIndex`	int	1	1-basert startposisjon
`count`	int	50	Antall resultater per side

GET /Users?startIndex=1&count=50
GET /Users?startIndex=51&count=50

Svaret inkluderer totalResults med det faktiske antallet brukere som matcher filteret — ikke antall returnert på siden. Bruk dette til å avgjøre om det finnes flere sider.

Entra ID sender alltid startIndex og count ved synkronisering (inkludert ved «Test Connection»). Begge parametrene behandles korrekt.

PATCH-semantikk (RFC 7644 §3.5.2)

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    { "op": "replace", "path": "active", "value": false },
    { "op": "add",     "path": "roles",  "value": [{ "value": "Admin", "primary": true }] },
    { "op": "remove",  "path": "phoneNumbers[type eq \"mobile\"]" }
  ]
}

Støttede op-verdier: add, remove, replace.

Brukerlivssyklus

IdP-handling	SCIM-kall	Effekt i Utleggsappen
Opprett bruker	`POST /Users`	Bruker + organisasjonstilknytning opprettes; sete reserveres
Endre attributter	`PATCH /Users/:id`	Felter oppdateres; rolleendring trer i kraft umiddelbart
Deaktiver	`PATCH ... active=false` eller `DELETE`	Kontoen blokkeres i denne organisasjonen (ikke globalt); innlogging blokkeres; sete frigjøres ved neste fakturaperiode
Reaktiver	`PATCH ... active=true`	Bruker gjenopplives med samme ID

Matching av eksisterende brukere

Ved POST /Users matcher serveren på userName (e-post). Hvis en bruker allerede finnes i Utleggsappen med samme e-post, kobles SCIM-identiteten til den eksisterende kontoen i stedet for å opprette en duplikat.

Vanlige fallgruver

Departments-format må være [departmentCode] [departmentName] — bare tall eller bare tekst gir 400.
Roller fra grupper provisjoneres ikke — IdP-en din må sende roles-attributtet eksplisitt med primary: "True".
employeeNumber har strenge regler — maks 20 tegn, kun bokstaver, tall og bindestrek.
Manager må eksistere og tilhøre samme organisasjon — referanse til ukjent ID eller ID fra en annen org gir 400/404.
Bulk støttes ikke — provisjoner én og én.
Bare eq støttes i filtre — bruk av andre operatorer (f.eks. co, sw) gir 400.
Sete-konsekvenser: POST /Users bruker en lisens. Sjekk seteforbruk under Abonnement.
SCIM krever riktig abonnement — organisasjonens plan må inkludere SCIM-provisjonering. Mangler planen denne tilgangen, returnerer API-et 402 Payment Required. Dette er et terminalt svar; IdP-en bør ikke prøve på nytt automatisk. Kontakt support for å oppgradere abonnementet.
Deaktivering er organisasjonsscoped — active=false blokkerer brukeren kun i denne organisasjonen, ikke i eventuelle andre organisasjoner brukeren er medlem av.

Konfigurasjonseksempler per IdP

Microsoft Entra ID

Tenant URL: https://api.utlegg.app/organizations/{organization_handle}/scim
Secret token: din PAT (ua_...)
Mappings: bruk default Entra-til-SCIM + custom mapping for enterprise.department (f.eks. Join(" ", [departmentCode], [departmentName])).

Okta

Connector: SCIM 2.0
Base URL: https://api.utlegg.app/organizations/{organization_handle}/scim/
API token: din PAT
Authentication mode: HTTP Header Authorization: Bearer ...
Provisioning Actions: Push New Users ✅, Push Profile Updates ✅, Push Groups ❌ (ikke støttet)

Google Workspace

Bruker SAML SSO + auto-provisioning via SCIM. Kontakt support for støttet konfigurasjon.

1. Endpoint​

Tilgjengelige underressurser​

2. Autentisering​

3. ResourceTypes​

4. Schema​

Core schema​

Enterprise extension​

ServiceProviderConfig​

Filtre (RFC 7644)​

Paginering​

PATCH-semantikk (RFC 7644 §3.5.2)​

Brukerlivssyklus​

Matching av eksisterende brukere​

Vanlige fallgruver​

Konfigurasjonseksempler per IdP​

Microsoft Entra ID​

Okta​

Google Workspace​

Se også​