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-endpoint niet om verbinding te maken met bestaande SCIM-endpoints zoals Entra ID of Google Workspaces. Deze beperking bestaat omdat geautomatiseerde accountprovisioning vanuit een van deze systemen de Zivver Synctool vereist.

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

Hoe weet ik of mijn organisatie Organisatie-Eenheden gebruikt?

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 2026-06-18