# Verbindingen

Laat gebruikers zich aanmelden via een externe Identity Provider (OIDC, SAML, Microsoft Entra, social), met accountkoppeling en JIT-aanmaak.

> **Opmerking over abonnementen:** Socialproviders (zoals Google, Apple, GitHub en vele andere) maken deel uit van elk abonnement. Enterprise-providers (generiek OIDC/SAML, Microsoft Entra, Okta, Auth0, Ping Identity, Keycloak, OneLogin, JumpCloud, DATEV, de aggregators voor elektronische identiteiten Criipto en Signicat, en de Duitse eID) vereisen de functie **enterprise identity brokering**, die is inbegrepen vanaf het Advanced-abonnement (en in Trial).

Met een **verbinding** kunnen uw gebruikers zich aanmelden met een *externe* Identity Provider, een optie "Aanmelden met…" op het aanmeldingsscherm. Het platform delegeert de authenticatie aan de provider, ontvangt het profiel van de gebruiker terug en koppelt dat aan een bestaand account of maakt een nieuw account aan. In protocoltermen treedt het platform op als Relying Party (OIDC) of Service Provider (SAML); de externe provider is de Identity Provider.

U beheert verbindingen in de Admin Console onder **Integraties → Verbindingen**.

## Beschikbare providers

Verbindingen komen in drie groepen.

**Generiek** (op standaarden gebaseerd, meer dan één keer configureerbaar):

| Provider | Protocol | Typisch gebruik |
|---|---|---|
| **OpenID Connect (generic)** | OIDC | Elke standaardconforme OIDC-Identity Provider. |
| **SAML 2.0 (generic)** | SAML | Elke SAML 2.0-Identity Provider. |

**Enterprise:**

| Provider | Protocol | Typisch gebruik |
|---|---|---|
| **Microsoft Entra** | OIDC | Aanmelden met een Microsoft Entra-tenant (werk of school). |
| **Okta** | OIDC | Aanmelden met een Okta Workforce-org. Vereist uw Okta-domein. |
| **Auth0** | OIDC | Aanmelden met een Auth0-tenant. Vereist uw Auth0-domein. |
| **Ping Identity (PingOne)** | OIDC | Aanmelden met een PingOne-omgeving. Vereist de PingOne-host en de environment ID. |
| **Keycloak** | OIDC | Aanmelden met een Keycloak-Realm. Vereist de server-URL en de Realm. |
| **OneLogin** | OIDC | Aanmelden met een OneLogin-account. Vereist uw OneLogin-domein. |
| **JumpCloud** | OIDC | Aanmelden met een JumpCloud-account. |
| **DATEV** | OIDC | Aanmelden met een DATEV-account (belastingadviseurs en hun cliënten). |
| **Criipto** | OIDC | Europese elektronische identiteiten (MitID, BankID, itsme en meer) via één verbinding met uw Criipto-tenant. |
| **Signicat** | OIDC | Europese elektronische identiteiten via één verbinding met uw Signicat-account. |
| **German eID (Online-Ausweis)** | OIDC | Aanmelden met de Duitse identiteitskaart via AusweisIDent. |

**Social en consumer** (elk één keer geconfigureerd): Amazon, Apple, Basecamp, Bitbucket, Box, DigitalOcean, Discord, Docusign, Dropbox, Facebook, Figma, Fitbit, FreshBooks, GitHub, GitLab, Google, Hugging Face, Intuit (QuickBooks), Kakao, Klarna, LINE, LinkedIn, Microsoft account, netID, PayPal, Salesforce, Slack, SoundCloud, Spotify, Strava, TikTok, Twitch, Vimeo, WordPress.com, X, Xero en Yahoo.

De generieke OIDC- en SAML-verbindingen kunnen meer dan één keer worden geconfigureerd (voor verschillende providers); elke met naam genoemde provider wordt één keer geconfigureerd. Er komen na verloop van tijd nieuwe providers bij, dus het aanmaakscherm is de maatgevende lijst.

De lijst met verbindingen toont een banner wanneer u het aantal verbindingen van uw abonnement bereikt; leeg of verwijder een verbinding om er een toe te voegen.

[Image: De lijst met verbindingen met drie geconfigureerde Identity Providers]

## Een verbinding toevoegen

1. Kies op de pagina Verbindingen **Verbinding maken** en selecteer een provider.
2. Bekijk de **Vereisten voor de integratie** die de verbinding toont, bijvoorbeeld het registreren van een applicatie bij de externe provider om een client ID en secret te verkrijgen, en bevestig.
3. Vul het configuratieformulier in (zie hieronder).
4. Sla op. Nieuwe verbindingen starten **Uitgeschakeld**; schakel een verbinding in wanneer u er klaar voor bent dat ze op het aanmeldingsscherm verschijnt.

### Configuratievelden

Elke verbinding heeft een **Naam** en een doel-**Directory** nodig: de directory waarin nieuwe gebruikers die via deze verbinding worden aangemaakt, worden geplaatst. Zie [Gebruikersdirectory's](https://dts-identity.com/nl/docs/directories/user-directories.md).

De protocolspecifieke velden zijn:

- **Generiek OIDC**: de discovery-(configuratie-)URL van de provider, een client ID, een client secret en de aan te vragen scopes (standaard `openid profile email`). De discovery-URL wordt telkens opnieuw gelezen, zodat de verbinding de eindpunten en sleutels van de provider overneemt zonder dat u ze opnieuw invoert.
- **Microsoft Entra**: een client ID, een client secret en de **tenant ID** (of `common` voor multi-tenant). De eindpunten van de provider komen uit het discovery-document van Microsoft voor die tenant.
- **Okta**: een client ID, een client secret en uw **Okta-domein** (bijvoorbeeld `acme.okta.com`, een preview-org of een eigen domein). Maak in de Okta Admin Console een OIDC Web Application aan en wijs die toe aan de gebruikers die zich moeten kunnen aanmelden.
- **Auth0**: een client ID, een client secret en uw **Auth0-domein** (bijvoorbeeld `acme.eu.auth0.com`, of een eigen domein). Maak in het Auth0 Dashboard een Regular Web Application aan.
- **Ping Identity (PingOne)**: een client ID, een client secret, de **PingOne-host** (de regionale host zoals `auth.pingone.com` of `auth.pingone.eu`, of een eigen domein) en de **environment ID**.
- **Keycloak**: een client ID, een client secret, de **server-URL** en de **Realm**. Neem bij Keycloak 16 en ouder het basispad `/auth` op in de server-URL. Schakel clientverificatie in, zodat de client vertrouwelijk is.
- **OneLogin**: een client ID, een client secret en uw **OneLogin-domein** (bijvoorbeeld `acme.onelogin.com`). Stel de verificatiemethode voor het token-eindpunt van de applicatie in op **POST**.
- **JumpCloud**: een client ID en een client secret uit een aangepaste OIDC-applicatie. Stel het clientverificatietype ervan in op **Client Secret Post**.
- **DATEV**: een client ID en een client secret uit een app in het DATEV Developer Portal die is aangemeld voor het product "Login with DATEV". Productietoegang volgt na een technische beoordeling.
- **Criipto**: uw Criipto-tenantdomein (bijvoorbeeld `acme.criipto.id` of een eigen domein), een client ID, een client secret en de te gebruiken elektronische identiteit. Omdat de elektronische identiteit per verbinding vastligt, voegt u voor elke elektronische identiteit die u wilt aanbieden een aparte verbinding toe.
- **Signicat**: uw Signicat-accountdomein (bijvoorbeeld `acme.signicat.com`), een client ID, een client secret en de te gebruiken elektronische identiteit. Voeg één verbinding per elektronische identiteit toe.
- **German eID (Online-Ausweis)**: de omgeving (productie of referentie), plus een client ID en een client secret van AusweisIDent. AusweisIDent beheert de eID-server en houdt het berechtigingscertificaat, zodat u via standaard-OIDC integreert.
- **Kakao**: een REST API-key (client ID) en een client secret. Schakel in de Kakao Developers-console Kakao Login in, activeer OpenID Connect onder de geavanceerde instellingen (vereist om een ID token te ontvangen) en configureer de consent items. Toegang tot het e-mailadres vereist een Kakao Business App.
- **netID**: een client ID en een client secret van een dienst die u in het netID-ontwikkelaarsportaal registreert. Een nieuwe dienst start in een sandbox voor vrijgegeven testgebruikers; vraag vrijgave aan voor productiegebruik.
- **Intuit (QuickBooks)**: een client ID en een client secret uit een app in het Intuit Developer-portaal. Productiesleutels worden uitgegeven nadat Intuit zijn app-beoordeling heeft afgerond.
- **De meeste socialproviders**: een client ID (soms anders aangeduid, bijvoorbeeld de client ID van Slack, de key van Bitbucket, de application ID van GitLab, de integration key van Docusign) en een bijbehorend secret. Volg de installatiehandleiding van elke provider voor de exacte veldnamen.
- **Providers met een host of regio**: Salesforce, GitLab en Docusign voegen een veld **host** toe (bijvoorbeeld een Salesforce My Domain, een zelfbeheerde GitLab-instantie, of de productie- versus ontwikkelaarshost van Docusign), zodat de verbinding de juiste instantie aanspreekt.
- **Apple**: een Services ID (de client ID), uw team ID, de key ID en de inhoud van de `.p8`-privésleutel die u bij Apple downloadt. De privésleutel wordt versleuteld opgeslagen en nooit teruggetoond; het client secret dat Apple vereist, wordt er automatisch uit gegenereerd.
- **Generiek SAML**: de entry-point-(aanmeldings-)URL van de provider, zijn Entity ID en zijn ondertekeningscertificaat in PEM-vorm, rechtstreeks ingevoerd. De eigen callback-(ACS-)URL en Entity ID van het platform staan in de installatiehandleiding van de verbinding, zodat u ze aan de kant van de provider kunt registreren.

Secrets en privésleutels worden ingevoerd in velden die leeg blijven wanneer u een bestaande verbinding bewerkt: laat een secretveld leeg om de opgeslagen waarde te behouden. Secrets worden nooit in leesbare vorm teruggetoond of in logs geschreven.

Wanneer u de verbinding inricht, toont elke handleiding ook de **callback-URL** die u bij de provider registreert, zodat de provider het aanmeldingsantwoord naar dit platform terugstuurt.

### Routering op maildomein (Home Realm Discovery)

Schakel **Home Realm Discovery** op een verbinding in en voer een of meer **Maildomeinen** in. Voert een gebruiker een e-mailadres in waarvan het domein overeenkomt, dan wordt die persoon rechtstreeks naar die provider gestuurd in plaats van naar het wachtwoordscherm, zodat niemand de juiste knop "Aanmelden met…" hoeft te kiezen. Voer de domeinen in als een door komma's gescheiden lijst (bijvoorbeeld `acme.com, acme.co.uk`).

- Een verbinding met ingestelde maildomeinen wordt **niet als knop** op de aanmeldingspagina getoond; ze is alleen bereikbaar via de domeinroutering (of via een directe verbindingslink). Dat houdt het aanmeldingsscherm overzichtelijk wanneer er meerdere enterprise-providers zijn geconfigureerd.
- Een domein kan aan **slechts één** verbinding worden toegewezen; het opslaan van een tweede verbinding met hetzelfde domein wordt geweigerd.
- Gebruikers van wie het maildomein niet wordt gerouteerd, en gebruikers die zich met een gebruikersnaam aanmelden, gaan door naar het gewone wachtwoordscherm.
- Het e-mailadres wordt als `login_hint` aan een OIDC-provider doorgegeven, zodat die het kan voorinvullen en de gebruiker het niet nog een keer hoeft in te voeren. SAML-providers ontvangen het niet (een SAML Request voor de aanmelding kan het niet betrouwbaar meedragen).
- Start een applicatie de aanmelding met een bekend e-mailadres (een OIDC-`login_hint`) in een gerouteerd domein, dan wordt de gebruiker rechtstreeks naar de provider gestuurd, zonder eerst het aanmeldingsscherm te zien.
- Wordt Home Realm Discovery uitgeschakeld (of worden de domeinen ervan gewist), dan verschijnt de knop van de verbinding weer op de aanmeldingspagina.

Is een gerouteerde provider tijdelijk verkeerd geconfigureerd en moet u voor een account in dat domein bij het wachtwoordscherm komen, voeg dan `?noHrd=1` toe aan de aanmeldings-URL om de routering voor dat bezoek over te slaan.

### Waarom u uw eigen provider-app registreert

Voor elke verbinding (een socialprovider zoals GitHub of LinkedIn, of een enterprise-provider zoals Okta of Microsoft Entra) registreert u een OAuth-applicatie *bij de provider* en levert u hier haar client ID en secret, in plaats van een gedeelde te gebruiken. Dat is bewust zo:

- Het toestemmingsscherm toont **uw** naam en logo, geen generieke.
- De app vraagt precies de **scopes aan die u nodig hebt**.
- De callback wordt naar **uw eigen domein** geleid, zodat afmelden en step-up-MFA correct werken.

Het scherm met vereisten van de verbinding somt op wat u vooraf moet registreren.

## Accountkoppeling

Keert een gebruiker via een verbinding terug, dan herkent het platform die persoon aan de stabiele identifier die de provider levert (niet aan het e-mailadres) en meldt het die aan op het gekoppelde account, waarbij naam en afbeelding bij de provider worden ververst.

Om accountovername te voorkomen geldt: meldt de provider een e-mailadres dat al bij een **ander** account hoort dat niet aan deze verbinding is gekoppeld, dan wordt de aanmelding **geweigerd** in plaats van de twee stilzwijgend samen te voegen. Er is geen beheerdersstap "accounts samenvoegen", en een binnenkomend (zeker een niet-geverifieerd) e-mailadres neemt nooit een bestaand account over. Het e-mailadres van de verbinding wordt alleen op een account overgenomen wanneer de verbinding een **Vertrouwde bron** is, de provider het e-mailadres als geverifieerd bevestigt en het domein van dat adres niet door een andere directory is gereserveerd (zie de reservering van maildomeinen onder [Gebruikersdirectory's](https://dts-identity.com/nl/docs/directories/user-directories.md)).

## Just-in-time-aanmaak van gebruikers

Meldt iemand zich voor het eerst via een verbinding aan en bestaat er geen passend account, dan maakt het platform er **just in time** een aan:

- De nieuwe gebruiker wordt in de geconfigureerde **Directory** van de verbinding geplaatst.
- Het profiel (naam, e-mailadres, afbeelding) wordt van de provider overgenomen.
- De gebruiker heeft geen wachtwoord en meldt zich alleen via dezelfde verbinding aan.

Hoe het nieuwe account wordt geactiveerd, hangt af van de instelling **Vertrouwde bron**:

- Is de verbinding als **Vertrouwde bron** gemarkeerd *en* bevestigt de provider dat het e-mailadres geverifieerd is, dan wordt het account meteen geactiveerd.
- Anders ontvangt de gebruiker een activeringsmail en moet die het adres verifiëren voordat het account actief wordt.

Socialproviders gelden standaard als vertrouwd; de generieke OIDC- en SAML-verbindingen standaard als niet-vertrouwd, omdat u een e-mailclaim alleen zou moeten vertrouwen van een provider die u beheert of hebt geverifieerd.

### Providers zonder e-mailadres

Sommige providers geven geen e-mailadres vrij (bijvoorbeeld X, Strava, Fitbit, SoundCloud, Vimeo en TikTok). De verbindingen voor elektronische identiteiten (Criipto, Signicat en de Duitse eID) geven eveneens een geverifieerde naam en een nationale identifier terug in plaats van een e-mailadres. Aanmelden via een van deze werkt gewoon en maakt nog steeds een account aan, maar dat account heeft geen e-mailadres: er wordt geen activeringsmail verstuurd, en het kan niet op e-mailadres aan een bestaand account worden gekoppeld. De gebruiker kan later in het eigen accountportaal een e-mailadres toevoegen en verifiëren, wat ook herstel per e-mail en alle e-mailgebaseerde multifactoropties mogelijk maakt.

Enkele providers geven een e-mailadres terug dat ze niet verifiëren (Spotify bijvoorbeeld). Dat adres wordt op het nieuwe account opgeslagen, maar als niet-geverifieerd behandeld en nooit op een ander bestaand account overgenomen, zodat het account uw normale verificatieregels blijft volgen.

### Apple

Apple geeft de naam van de gebruiker **alleen bij de allereerste aanmelding** terug, dus een terugkerende Apple-gebruiker behoudt de naam die toen is vastgelegd. Gebruikers die voor Apples optie **Hide My Email** kiezen, melden zich aan met een privé-relay-adres, wat gewoon werkt. De `.p8`-privésleutel die u invoert, wordt versleuteld opgeslagen en uitsluitend gebruikt om het kortlevende client secret te genereren dat Apple vereist.

## Instellingen per verbinding

| Instelling | Effect |
|---|---|
| **Naam** | De aanduiding die in de Admin Console en in het auditlogboek wordt getoond. |
| **Directory** | Waar just-in-time-gebruikers worden aangemaakt. |
| **Home Realm Discovery** | Indien ingeschakeld, de maildomeinen die naar deze verbinding worden gerouteerd. Een gebruiker die een e-mailadres met een van deze domeinen invoert, wordt rechtstreeks naar deze provider gestuurd, en de verbinding wordt niet als knop op de aanmeldingspagina getoond. Een domein kan bij slechts één verbinding horen. |
| **Vertrouwde bron** | Bepaalt de automatische activering en of het e-mailadres van de provider wordt overgenomen. |
| **Ingeschakeld** | Alleen ingeschakelde verbindingen verschijnen op het aanmeldingsscherm. |

U kunt een verbinding uitschakelen om haar van het aanmeldingsscherm te halen zonder haar te verwijderen, of haar helemaal verwijderen. Beide acties vragen om bevestiging door de naam van de verbinding te typen.

## Referentie

| Begrip | Betekenis |
|---|---|
| Verbinding | Het delegeren van de aanmelding aan een externe Identity Provider. |
| Accountkoppeling | Het koppelen van een terugkerende gefedereerde identiteit aan een bestaand account. |
| Just-in-time-(JIT-)aanmaak | Het aanmaken van een nieuw account bij de eerste gefedereerde aanmelding van een gebruiker. |
| Vertrouwde bron | Een verbinding waarvan het platform de claim over een geverifieerd e-mailadres vertrouwt voor automatische activering. |
| Home Realm Discovery | Het automatisch routeren van een aanmelding naar een verbinding op basis van het maildomein dat de gebruiker invoert. |

## Probleemoplossing

- **De provider geeft bij de callback een fout terug.** De meest voorkomende oorzaak is een redirect-(callback-)URL die niet bij de externe provider is geregistreerd, of een client ID of secret dat niet overeenkomt. Registreer de exacte callback-URL die bij het aanmaken van de verbinding werd getoond, en controleer de credentials opnieuw.
- **De tokenuitwisseling mislukt met een `invalid_client`-fout.** Sommige providers (bijvoorbeeld OneLogin en JumpCloud) zetten de verificatiemethode voor het token-eindpunt van de applicatie standaard op Basic. Zet die in de applicatie-instellingen van de provider op **POST** (client secret post).
- **Gebruikers met een bepaald maildomein worden rechtstreeks naar een externe provider gestuurd.** Dat domein is toegewezen aan de maildomeinen van een verbinding, wat de domeingebaseerde routering (Home Realm Discovery) inschakelt. Verwijder het domein uit de verbinding om de routering te beëindigen. Om eenmalig bij het wachtwoordscherm te komen (bijvoorbeeld wanneer de provider verkeerd is geconfigureerd), voegt u `?noHrd=1` toe aan de aanmeldings-URL.
- **De Kakao-aanmelding mislukt of geeft geen ID token terug.** Kakao geeft alleen een ID token uit wanneer OpenID Connect is geactiveerd in de geavanceerde Kakao Login-instellingen van de app. Een ontbrekend consent item breekt de aanmelding eveneens af; configureer de aangevraagde consent items (nickname, profielafbeelding) in de Kakao-console.
- **Een terugkerende gebruiker belandt op een nieuw, leeg account.** Accountkoppeling koppelt een gefedereerde identiteit op geverifieerd e-mailadres aan een bestaand account. Geeft de provider geen geverifieerd e-mailadres terug, of wijkt het adres af van het opgeslagen adres, dan wordt er geen overeenkomst gevonden en wordt een apart account aangemaakt. Bevestig dat de provider een claim over een geverifieerd e-mailadres vrijgeeft.
- **De eerste aanmelding via een verbinding wordt geweigerd met een domeinfout.** Het domein van het e-mailadres is door een andere directory gereserveerd. Een domein dat bij één directory staat, kan niet worden opgeëist door elders aangemaakte gebruikers, ook niet bij just-in-time-aanmelding via federatie. Verplaats de reservering of gebruik een adres in een niet-gereserveerd domein.
- **Een gefedereerde gebruiker wordt aangemaakt, maar blijft inactief.** Nieuwe accounts worden alleen automatisch geactiveerd voor een vertrouwde verbinding die een geverifieerd e-mailadres teruggeeft. Bij andere verbindingen volgt het account uw normale verificatie- en levenscyclusregels.

Zie ook de [woordenlijst](https://dts-identity.com/nl/docs/reference/glossary.md).
