> Accounts synchroniseren met Zivver via SCIM 2.0

Accounts synchroniseren met Zivver via SCIM 2.0

Introductie

Dit artikel legt uit hoe je direct kunt communiceren met het Zivver SCIM V2 API-eindpunt. Je kunt deze informatie gebruiken als je organisatie Zivver-accounts automatisch wil beheren door een eigen SCIM-koppeling te bouwen.

Info

Gebruik het Zivver SCIM V2 API-eindpunt niet om verbinding te maken met bestaande SCIM-eindpunten zoals Entra ID of Google Workspaces. Dit is een beperking. Voor geautomatiseerde accountprovisioning vanuit een van deze systemen raden we de Zivver Synctool aan.

Accountmanagement in Zivver

Zivver-accounts kun je handmatig beheren via het Zivver-beheerportaal, of automatisch via de Zivver System for Cross-domain Identity Management (SCIM) API. Zivver volgt de SCIM 2.0-specificaties. Voor organisaties met meer dan 100 medewerkers adviseert Zivver om het accountbeheer te automatiseren. Zivver raadt hiervoor de Zivver Synctool aan.

Zivver maakt onderscheid tussen normale accounts en functionele accounts. Elk accounttype wordt op een andere manier beheerd, en beide typen worden in deze handleiding uitgelegd.

Accounttype	Beschrijving
Normaal	Persoonlijk account waarop een gebruiker kan inloggen.
Functioneel	Gedeeld account waarop je niet rechtstreeks kunt inloggen. Met Gedelegeerde toegang kan een gebruiker Zivver-berichten versturen en ontvangen vanuit een functioneel account.

Verbinding maken met het Zivver SCIM v2-eindpunt

Verbinding
URL	`https://app.zivver.com/api/scim/v2/`
Port	`443`

De verbinding wordt geauthenticeerd met een Bearer Token. Een Zivver-beheerder kan hiervoor een API-sleutel aanmaken in het Zivver-beheerportaal. Een SCIM-client moet de in Zivver gegenereerde API-sleutel als token meesturen in de Authorization-header, zoals beschreven in RFC6750 sectie 2.1:

Clients SHOULD make authenticated requests with a bearer token using the “Authorization” request header field with the “Bearer” HTTP authorization scheme.

Voorbeeld:

Authorization: Bearer {base64-gecodeerde Zivver API-sleutel}

Info

Het bearer token coderen in base64
De HTTP-specificaties vereisen dat de client het bearer token in base64 codeert. Bestaande tools of libraries doen dit meestal automatisch.

Ondersteunde SCIM-bewerkingen

De volgende SCIM-bewerkingen worden ondersteund door het Zivver SCIM v2-eindpunt:

Create: POST https://app.zivver.com/api/scim/v2/{resource}
Read: GET https://app.zivver.com/api/scim/v2/{resource}/{id}
Replace: PUT https://app.zivver.com/api/scim/v2/{resource}/{id}
Delete: DELETE https://app.zivver.com/api/scim/v2/{resource}/{id}
Update: PATCH https://app.zivver.com/api/scim/v2/{resource}/{id}
Search: GET https://app.zivver.com/api/scim/v2/{resource}

Waarschuwing

Delete: DELETE
Het verwijderen van Zivver-accounts is onomkeerbaar. Verwijderde gegevens kunnen niet worden teruggezet. Zivver adviseert om de waarde van het attribuut active op false te zetten (suspend) in plaats van het account te verwijderen.

Info

Update: PATCH
De ondersteuning voor deze bewerking is beperkt tot Microsoft Entra ID. Voor andere clients wordt geadviseerd om in plaats daarvan de PUT-bewerking te gebruiken.

Zivver-gebruikersaccounts beheren

Je kunt inloggen op een Zivver-gebruikersaccount met een Zivver-wachtwoord of via Single Sign-On (SSO). Zivver gebruikt het SCIM-resourcetype Users om gebruikersaccounts te beheren, gebaseerd op het volgende schema:

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

Het user-object moet common attributes en singular attributes bevatten. Daarnaast gebruikt Zivver multi-value attributes, de enterprise user schema extension en een custom extension schema.

Gemeenschappelijke user-objectattributen

RFC-7643: Common Attributes

De volgende gemeenschappelijke user-objectattributen worden door Zivver geleverd en kunnen niet worden aangepast.

id: unieke identifier die door Zivver wordt verstrekt
De id wordt door Zivver verstrekt en kan niet worden aangepast. De {id} wordt gebruikt voor SCIM-bewerkingen.
meta.resourceType: user
meta.created: aanmaakdatum van het account
De aanmaakdatum wordt door Zivver verstrekt en kan niet worden aangepast.
meta.location: /scim/v2/Users/{id}

Enkelvoudige user-objectattributen

RFC-7643: Singular attributes

Zivver gebruikt de volgende verplichte en optionele enkelvoudige attributen.

userName: primair e-mailadres (verplicht)
Zivver identificeert een account aan de hand van het primaire e-mailadres.
name.formatted: weergavenaam (verplicht)
Zivver gebruikt deze naam om ontvangers te tonen wie een bericht heeft verzonden. Vul dit veld bij voorkeur met een voornaam en achternaam.
nickName: bijnaam (optioneel)
Zivver gebruikt deze waarde in de aanhef van notificatieberichten.
active: of het account actief of geschorst is (verplicht)
Zivver gebruikt dit attribuut om accounts te schorsen. Schors een account wanneer een medewerker uit dienst gaat. Een geschorste gebruiker wordt opnieuw geactiveerd wanneer de waarde true is.

Multi-value user-objectattributen

RFC-7643: Multi-value attributes

Zivver gebruikt de volgende optionele multi-value attributen.

phoneNumbers: het eerste telefoonnummer in de lijst wordt gebruikt voor 2FA (optioneel)
Zorg ervoor dat dit nummer sms-berichten kan ontvangen.

Enterprise User Schema Extension

RFC-7643: Enterprise user schema extension

Zivver gebruikt het volgende extra attribuut wanneer je organisatie met Organisatie-Eenheden werkt.

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

division: de Organisatie-Eenheid waartoe het account behoort (optioneel)
Zivver gebruikt dit attribuut om het account aan de juiste Organisatie-Eenheid te koppelen.

Info

Hoe weet ik of mijn organisatie Organisatie-Eenheden gebruikt?
Als dit zo is, heb je toegang tot de pagina Organisatie-Eenheden. Heb je geen toegang, dan gebruikt je organisatie deze functie niet of heb je geen beheerdersrechten.

Zivver’s Custom Extension Schema

RFC-7643: Custom schema extension

Zivver breidt de bovenstaande attributen uit met het volgende schema:

urn:ietf:params:scim:schemas:zivver:0.1:User

Dit schema bevat de volgende attributen:

password: Zivver-wachtwoord wanneer SSO niet wordt gebruikt (verplicht tenzij SSO wordt gebruikt)
Dit wachtwoord wordt gebruikt om de encryptiesleutels te genereren. Het wachtwoord is alleen nodig voor de eerste login; daarna maakt de gebruiker een eigen wachtwoord.
SsoAccountKey: ZivverAccountKey wanneer SSO wordt gebruikt (verplicht bij SSO)
Dit attribuut wordt gebruikt om de encryptiesleutels te genereren.
Info
Belangrijke informatie over de ZivverAccountKey
Deze waarde moet lang, uniek en random zijn. Bij voorkeur genereert je organisatie deze sleutel zelf. Als alternatief kan objectGUID worden gebruikt, maar dit vormt een beveiligingsrisico omdat deze waarde vaak in meerdere systemen wordt hergebruikt. Gebruik geen objectSID of vergelijkbare AD-attributen omdat deze voorspelbaar zijn.
aliases: lijst met e-mailaliassen (optioneel)
De gebruiker kan Zivver-berichten ontvangen op deze aliassen.
delegates: lijst met e-mailadressen die volledige toegang hebben (optioneel)
Gebruikers kunnen berichten lezen en verzenden namens andere accounts.
Info
Belangrijke informatie over delegates
delegates is een lijst van e-mailadressen, niet van user-{id}ʼs.

Voorbeeld van minimale user-representatie

Het volgende is een niet-normatief voorbeeld van de minimale vereiste SCIM-representatie in JSON-formaat.

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User", "urn:ietf:params:scim:schemas:zivver:0.1:User"],
  "meta": {
    "resourceType": "User",
    "created": "2010-01-23T04:56:22Z",
    "location": "/scim/v2/Users/2819c223-7f76-453a-919d-413861904646"
  }
  "active":true,
  "id": "2819c223-7f76-453a-919d-413861904646",
  "name": {
    "formatted": "Barbara Jensen"
  },
  "urn:ietf:params:scim:schemas:zivver:0.1:User": {
    "SsoAccountKey": "48452ce3-9346-4ef0-9528-19btf6d4e545"
  }
  "userName": "bjensen@example.com",
}

Voorbeeld van volledige user-representatie

Het volgende is een niet-normatief voorbeeld van een volledig ingevulde SCIM-userrepresentatie in JSON-formaat.

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User", "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User", "urn:ietf:params:scim:schemas:zivver:0.1:User"],
  "meta": {
    "resourceType": "User",
    "created": "2010-01-23T04:56:22Z",
    "location": "/scim/v2/Users/2819c223-7f76-453a-919d-413861904646"
  }
  "active":true,
  "id": "2819c223-7f76-453a-919d-413861904646",
  "name": {
    "formatted": "Barbara Jensen"
  },
  "nickName": "Babs Jensen",
  "phoneNumbers": [
    {
      "value":"555-555-5555"
    }
  ],
  "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
    "division": "Development"
  },
  "urn:ietf:params:scim:schemas:zivver:0.1:User": {
    "SsoAccountKey": "48452ce3-9346-4ef0-9528-19btf6d4e545",
    "aliases": ["barbarajensen@example.com", "barbara.jensen@example.com"],
    "delegates": ["jdoe@example.com", "hpeterson@example.com"]
  }
  "userName": "bjensen@example.com"
}

Functionele Zivver-accounts beheren

Functionele Zivver-accounts zijn gedeelde accounts. Als je Zivver-gebruikersaccount gedelegeerde toegang heeft tot een functioneel account, word je automatisch ingelogd op dat functionele account. In Zivver wordt het SCIM-resourcetype Groups gebruikt, gebaseerd op het volgende schema:

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

Het group-object moet een common attribute, een singular attribute en een multi-value attribute bevatten. Daarnaast gebruikt Zivver de enterprise user schema extension en een custom extension schema.

Gemeenschappelijke group-objectattributen

RFC-7643: Common attributes

De volgende gemeenschappelijke attributen worden door Zivver geleverd en kunnen niet worden aangepast.

externalId: primair e-mailadres (verplicht)
Zivver identificeert een groepsaccount aan de hand van het primaire e-mailadres. Omdat Groups niet altijd een userName hebben, moet externalId het primaire e-mailadres van het gedeelde account bevatten. Dit verschilt van het User-object, waarin het primaire e-mailadres in userName staat.

Zivver levert de volgende extra gemeenschappelijke attributen, dus het is niet nodig deze aan te maken.

id: unieke identifier (geleverd)
De id wordt door Zivver verstrekt en kan niet worden aangepast. Wordt gebruikt voor SCIM-bewerkingen.
meta.resourceType: Group (geleverd)
meta.created: aanmaakdatum account (geleverd)
De aanmaakdatum wordt door Zivver verstrekt en kan niet worden aangepast.
meta.location: /scim/v2/Groups/{id} (geleverd)

Enkelvoudige group-objectattributen

RFC-7643: Singular attributes

Verplicht attribuut voor group-objecten:

displayName: weergavenaam voor eindgebruikers (verplicht)
Zivver gebruikt deze naam om aan eindgebruikers te tonen hoe het account heet.

Multi-value group-objectattributen

RFC-7643: Multi-value attributes

Verplicht attribuut voor group-objecten:

members: gebruikers met volledige toegang tot het account (verplicht)
Bevat een lijst van Zivver user {id}-waarden die toegang hebben. Deze accounts kunnen berichten verzenden en ontvangen namens het functionele account.
Info
Belangrijke informatie over members
Gebruik de unieke {id} van gebruikers, niet e-mailadressen. Zie Voorbeeld volledige group-representatie.

Enterprise User Schema Extension

RFC-7643: Enterprise user schema extension

Gebruik dit attribuut alleen als je organisatie met Organisatie-Eenheden werkt.

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

division: Organisatie-Eenheid van het functionele account (optioneel)
Zivver gebruikt dit attribuut om het account aan de juiste Organisatie-Eenheid te koppelen.

Info

Zivver’s Custom Extension Schema

RFC-7643: Custom schema extension

urn:ietf:params:scim:schemas:zivver:0.1:Group

aliases: lijst met e-mailaliassen (optioneel)
Gebruikers van het functionele account kunnen berichten ontvangen op deze aliassen.

Voorbeeld minimale group-representatie

Het volgende is een niet-normatief voorbeeld van de minimale SCIM Group-representatie in JSON-formaat.

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
  "meta": {
    "resourceType": "Group",
    "created": "2010-01-23T04:56:22Z",
    "location": "/scim/v2/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a"
  }
  "displayName": "Department A",
  "externalId": "department@example.com",
  "id": "e9e30dba-f08f-4109-8486-d5c6a331660a",
  "members": [
  {
    "value": "2819c223-7f76-453a-919d-413861904646"
  }
  {
    "value": "5737d357-5a46-267n-111e-6783178326"
  }
  ]
}

Voorbeeld van volledige group-representatie

Het volgende is een niet-normatief voorbeeld van een volledig ingevulde SCIM Group-representatie in JSON-formaat.

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group", "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User", "urn:ietf:params:scim:schemas:zivver:0.1:Group"],
  "meta": {
    "resourceType": "Group",
    "created": "2010-01-23T04:56:22Z",
    "location": "/scim/v2/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a"
  }
  "displayName": "Department A",
  "externalId": "department@example.com",
  "id": "e9e30dba-f08f-4109-8486-d5c6a331660a",
  "members": [
  {
    "value": "2819c223-7f76-453a-919d-413861904646"
  }
  {
    "value": "5737d357-5a46-267n-111e-6783178326"
  }
  ],
  "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
    "division": "Development"
  },
  "urn:ietf:params:scim:schemas:zivver:0.1:Group": {
    "aliases": ["development@example.com"]
  }
}

Laatst bijgewerkt op 2025-11-19

Ik ben een Zivver-beheerder

Zivver instellen en beheren

Accounts synchroniseren met Zivver via SCIM 2.0

Introductie

Accountmanagement in Zivver

Verbinding maken met het Zivver SCIM v2-eindpunt

Ondersteunde SCIM-bewerkingen

Zivver-gebruikersaccounts beheren

Gemeenschappelijke user-objectattributen

Enkelvoudige user-objectattributen

Multi-value user-objectattributen

Enterprise User Schema Extension

Zivver’s Custom Extension Schema

Voorbeeld van minimale user-representatie

Voorbeeld van volledige user-representatie

Functionele Zivver-accounts beheren

Gemeenschappelijke group-objectattributen

Enkelvoudige group-objectattributen

Multi-value group-objectattributen

Enterprise User Schema Extension

Zivver’s Custom Extension Schema

Voorbeeld minimale group-representatie

Voorbeeld van volledige group-representatie