OAuth Koppeling

Handleiding: Externe Applicaties Koppelen (OAuth)

Via onze OAuth-module is het mogelijk om externe applicaties (zoals boekhoudpakketten, CRM-systemen of eigen interne tools) op een veilige manier toegang te geven tot Sidefish.

Deze handleiding legt je stap voor stap uit hoe je een nieuwe integratie opzet en welke instellingen je daarvoor moet gebruiken.

1. Een nieuwe OAuth Client aanmaken

Om een nieuwe integratie toe te voegen, ga je naar het portaal en navigeer je naar jouw Organisatie. Onder de tab Integraties vind je de mogelijkheid om OAuth clients te beheren. Klik op Nieuwe OAuth Client Aanmaken.

Er opent zich een scherm waarin je de volgende basisgegevens moet invullen:

• Applicatienaam: Geef de applicatie een duidelijke, herkenbare naam (bijv. "Exact Online Koppeling" of "Interne Rapportage Tool").
• Toegestane Redirect URI's: Als een gebruiker succesvol inlogt via onze applicatie, moet hij of zij worden teruggestuurd naar de externe applicatie. Vul hier de exacte webadressen (URL's) in waar de applicatie de gebruiker naartoe mag sturen. Druk op Enter na elke URL om deze toe te voegen.

2. Endpoints

De OAuth URLs zijn als volgt:

• Authorize URL: https://sidefish.app/api/v1/oauth/v2/auth
• Token URL: https://sidefish.app/api/v1/oauth/v2/token
• Revoke URL: https://sidefish.app/api/v1/oauth/v2/revoke

3. OAuth Flows (Grants) Begrijpen

Bij "Toegestane Grants" kies je op welke manier de externe applicatie verbinding mag maken. Welke je nodig hebt, hangt af van het type applicatie dat je wilt koppelen:

• Authorization Code
  • Wanneer gebruiken? Dit is de standaard en meest veilige methode voor webapplicaties.
  • Hoe werkt het? De eindgebruiker wordt doorgestuurd naar ons inlogscherm, logt in, en wordt daarna met een tijdelijke, veilige code teruggestuurd naar de externe applicatie.
• Client Credentials
  • Wanneer gebruiken? Voor geautomatiseerde achtergrondprocessen (server-tot-server communicatie).
  • Hoe werkt het? Er komt géén menselijke gebruiker aan te pas. De externe server gebruikt direct de Client ID en Client Secret om in te loggen namens de applicatie zelf.
• Refresh Token
  • Wanneer gebruiken? Bijna altijd in combinatie met 'Authorization Code'.
  • Hoe werkt het? Zorgt ervoor dat de gebruiker niet telkens opnieuw hoeft in te loggen wanneer zijn sessie verloopt. De applicatie kan zelf op de achtergrond een nieuw toegangsbewijs (token) aanvragen

4. Rechten Toewijzen (Scopes)

Het is cruciaal om een applicatie alleen de rechten te geven die het écht nodig heeft. Dit noemen we het principe van de minste privileges. Zo voorkom je dat een simpele rapportagetool per ongeluk gegevens kan wissen.

Via de overzichtelijke dropdown met zoekveld kan je eenvoudig de benodigde rechten (scopes) opzoeken en aanvinken.

Hier is een overzicht van de terminologie die we gebruiken:

• Klanten (customers): Toegang tot individuele klantendossiers.
• Klantengroepen (portfolios): Toegang tot portfolios waarin klanten gebundeld zijn.
• Acties (sessionrequests): Toegang tot sessies, aanvragen en onderliggende processtappen.
• Bestanden (files): Het mogen inzien of uploaden van bestanden en documenten.
• Gebruikers (users): Toegang tot de medewerkers/gebruikers binnen het platform.
• Quick Signing (quicksigningsetup): Toegang tot de snelle digitale handtekening modules.

Voor de meeste van deze onderdelen kan je apart kiezen tussen:

• Leesrechten (:read): De applicatie mag de gegevens alleen inzien of ophalen.
• Schrijfrechten (:write): De applicatie mag gegevens aanmaken, wijzigen of verwijderen

Opgelet: ALLES (Volledige toegang) Er is een speciale "ALLES" optie beschikbaar in de lijst. Vink deze alleen aan voor volledig vertrouwde, interne applicaties. Hiermee omzeil je alle specifieke veiligheidsrestricties en krijgt de applicatie god-mode toegang tot alle data!

5. Na het aanmaken: Client ID & Secret

Zodra je de integratie opslaat, genereert het systeem twee unieke sleutels:

1. Client ID: De openbare "gebruikersnaam" van de applicatie.
2. Client Secret: Het "wachtwoord" van de applicatie.

Opgelet: Veiligheid voorop! Behandel de Client Secret als een uiterst gevoelig wachtwoord. Deel deze nooit via onveilige kanalen zoals e-mail, Slack of Teams. Als je vermoedt dat de Secret is uitgelekt, dien je de integratie direct te verwijderen of opnieuw aan te maken!