App connector inrichten voor confidential client (Profit 9)

Je maakt een app connector aan voor een confidential client. Een confidential client kan een client secret veilig opslaan. De app connector biedt echter ook technieken waarbij dit niet nodig is.

Je kon een app connector op basis van OAuth inrichten met de methoden Client credentials flow en Authorization code flow. Hieronder zie je de uitbreidingen voor Profit 9.

Inhoud

  • Beschrijving
  • Technische informatie en endpoints
  • App connector aanmaken voor een Systeemservice
  • App connector aanmaken voor een Webapplicatie
  • Vervolgstappen
Beschrijving

In dit artikel is gave nieuwe functionaliteit verwerkt die beschikbaar is vanaf Profit 9.

Als je begint met een nieuwe app connector, dan baseer je deze op een Webapplicatie of Systeemservice. Deze keuze bepaalt je mogelijkheden bij de inrichting van de app connector. Een Systeemservice is altijd gebaseerd op de Client credentials flow, bij een Webapplicatie heb je de keuze tussen Client credentials flow en Authorization code flow.

Bij de Webapplicatie of Systeemservice maak je een keuze:

  • Je gebruikt client secrets (al bekend van Profit 8)

    Vanaf Profit 9 heeft de client secret een vaste geldigheidsduur van maximaal 2 jaar. Je kunt nu gebruik maken van een roterend client secret (je kunt meerdere client secrets per app connector opslaan).

    Als de laatste geldige client secret binnen 14 dagen verloopt, dan wordt dit gemeld op Profit Home. Als er nog een andere client secret is met een langere geldigheidsduur, dan is er geen melding op Profit Home.

    Je kunt de geldigheid van client secrets opvragen via de api. Als je de metainfo van een App Connector ophaalt, dan krijg je ook de client secret metadata terug inclusief de verloopdatum.

  • Je gebruikt JWT in plaats van een client secret (nieuw in Profit 9)

    Hierbij doe je een tokenaanvraag op basis van een eenmalige, kortlevende Json Web Token.

De toepassing van DPoP (Demonstrating Proof of Possession) is optioneel. DPoP koppelt een token aan een sleutelpaar dat de applicatie zelf aanmaakt. Bij elke aanroep stuurt de applicatie een ondertekend bewijs mee dat zij de bijbehorende private sleutel bezit. Profit accepteert het token alleen samen met een geldig bewijs, waardoor een onderschept token niet in een andere applicatie of op een ander apparaat werkt.

Technische informatie en endpoints

Verwijs je koppelpartner of de ontwikkelaar van je applicatie naar de API Docs voor een overzicht van de endpoints, codevoorbeelden, etc.

App connector aanmaken voor een Systeemservice

Een Systeemservice is altijd gebaseerd op de Client credentials flow. Er logt geen gebruiker in en de applicatie communiceert zelfstandig met Profit. Profit koppelt één systeemgebruiker aan een gebruikersgroep; alle aanroepen van de app connector lopen via de autorisatie van deze gebruikersgroep.

Bij de client credentials flow wordt altijd een nieuwe gebruikersgroep met een systeemgebruiker aangemaakt. De naam van de nieuwe gebruikersgroep en systeemgebruiker is gebaseerd op de naam van de nieuwe app connector.

Als de naam van de aan te maken gebruikersgroep al bestaat, dan gebruikt Profit de naam + een volgnummer.

Voorbeeld:

Je hebt de app connector Kassasysteem aangemaakt in omgeving 12345. Profit maakt de gebruikersgroep Kassasysteem aan met de systeemgebruiker 12345.Kassasysteem (de naam van de systeemgebruiker is Kassasysteem).

Je maakt nog een app connector Kassasysteem aan in omgeving 12345. Profit maakt de gebruikersgroep Kassasysteem 2 aan met de systeemgebruiker 12345.Kassasysteem2 (de naam van de systeemgebruiker is Kassasysteem).

  1. Ga naar: Algemeen / Beheer / App connector.
  2. Klik op: Nieuw.
  3. Vul de omschrijving in.
  4. Selecteer OAuth bij het veld Type authenticatie.
  5. Selecteer Systeemservice bij het veld Type applicatie.
  6. Bepaal of je DPOP wilt gebruiken.
  7. Bepaal de Clientauthenticatiemethode: op basis van een client secret of JWK (Jason web token).

    Bij de keuze voor JWK bepaal je in het veld Bron JWKS of je een bestand koppelt met de publieke sleutel, of dat je de publieke sleutel ophaalt via een URL.

    • Als je kiest voor JWKS-url dan vul je de URL in. Je kunt de URL naderhand nog wijzigen via de eigenschappen van de app connector. Profit haalt via deze URL de publieke ondertekeningssleutels op. De applicatie kan sleutels zonder handmatige wijziging in Profit roteren door de oude en nieuwe publieke sleutel tijdelijk tegelijk te publiceren.
    • Als je kiest voor Bestand, dan leg je na het voltooien van de wizard het certificaatbestand vast via de eigenschappen van de app connector (zie hieronder).

    Let op:

    Je kunt de bovenstaande keuzen niet meer wijzigen (behalve het veld DPoP).

    Na het aanmaken van de app connector maakt Profit automatisch een gebruikersgroep en een systeemgebruiker aan met de naam van de app connector.

  8. Klik op: Voltooien.
  9. De eigenschappen van de app connector worden geopend. Je kunt de OAuth client id kopiëren.

    Let op:

    Je kunt de OAuth client id wel raadplegen via de eigenschappen van de app connector, maar niet wijzigen.

  10. Afhankelijk van de authenticatiemethode moet je het volgende doen:
    • Als je gekozen hebt voor de clientauthenticatiemethode JWK in combinatie met het vastleggen van een bestand, dan leg je het certificaat vast op het tabblad Certificaten. Leg minimaal één X.509-certificaat vast. Profit gebruikt de publieke sleutel uit dit certificaat om de ondertekende JWT te controleren.
    • Als je gekozen hebt voor de clientauthenticatiemethode Client secret, dan maak je een nieuwe client secret aan op het tabblad Client secrets. Kopieer de client secret en bewaar deze op een veilige plaats. Na het voltooien van de client secret kan deze niet meer worden opgevraagd.
  11. Ga door met de Vervolgstappen (onderaan deze pagina).
App connector aanmaken voor een Webapplicatie

De applicatie draait op een webserver en die webserver bewaart een client secret. Profit richt deze in als Confidential client. Kies vervolgens één flow: de Client credentials flow voor zelfstandig werken met één gebruiker en autorisatiegroep, of de Authorization code flow voor werken namens een ingelogde gebruiker met één bestaande autorisatiegroep.

  1. Ga naar: Algemeen / Beheer / App connector.
  2. Klik op: Nieuw.
  3. Vul de omschrijving in.
  4. Selecteer OAuth bij het veld Type authenticatie.
  5. Selecteer Webapplicatie bij het veld Type applicatie.
  6. Bepaal of je DPOP wilt gebruiken.
  7. Bepaal of je de Client credentials flow en Authorization code flow wilt gebruiken.
    • Bij de Authorization code flow selecteer je de Profit-gebruikersgroep en vul je de redirect url in.
    • Bij de client credentials flow wordt altijd een nieuwe gebruikersgroep met een systeemgebruiker aangemaakt. De naam van de nieuwe gebruikersgroep en systeemgebruiker is gebaseerd op de naam van de nieuwe app connector.
  8. Bepaal de Clientauthenticatiemethode: op basis van een client secret of JWK (Jason web token.

    Let op:

    Je kunt de bovenstaande keuzen niet meer wijzigen, behalve het veld DPoP. Dit veld kun je na het aanmaken van de app connector nog aan- of uitvinken.

    Na het aanmaken van de app connector maakt Profit automatisch een gebruikersgroep en een systeemgebruiker aan met de naam van de app connector. Je

  9. Klik op: Voltooien.
  10. De eigenschappen van de app connector worden geopend. Je kunt de OAuth client id kopiëren.

    Let op:

    Je kunt de OAuth client id wel raadplegen via de eigenschappen van de app connector, maar niet wijzigen.

Client secret aanmaken:

Deze stap geldt alleen bij de Client credentials flow.

Omdat een client secret een vervaldatum heeft, kun je meerdere client secrets aanmaken. Dit is nodig voor een roterend client secret.

Let op:

Je kunt de OAuth client id raadplegen via het tabblad Algemeen, maar niet meer wijzigen.

De OAuth client secret zie je alleen bij het aanmaken van de secret.

In de weergave Client secrets zie je de eerste vier tekens van een client secret, zodat je dit kunt herkennen Dit is nieuw in Profit 9

  1. Ga naar het tabblad: Client secret.
  2. Klik op: Nieuw.
  3. Maak een client secret aan.
  4. Klik op: Volgende.
  5. Kopieer de OAuth secret en sla deze op een veilige plaats op.
  6. Klik op: Voltooien.
Vervolgstappen

Voer deze stappen uit na het aanmaken van een app connector.

Instellingen van de app connector volledig maken:

  • Selecteer de Get- en UpdateConnectoren die via de app connector mogen worden aangeroepen.

    Koppel de gewenste GetConnectoren aan de app connector. Met een GetConnector kan een externe applicatie gegevens ophalen uit Profit. Alleen de gekoppelde GetConnectoren kunnen in combinatie met deze app connector worden aangeroepen door een externe applicatie.

    Het koppelen kan op twee manieren:

    • Handmatig. Klik op Nieuw. Vink de gewenste GetConnectoren aan en klik op Voltooien om deze te koppelen.
    • Via een import. Klik op Acties / Importeren en importeer de GetConnectoren, bijvoorbeeld GetConnectoren die je eerder van een partner gekregen hebt.

    Koppel de gewenste UpdateConnectoren aan de app connector. Met een UpdateConnector kan een externe applicatie gegevens aanmaken, wijzigen of verwijderen in Profit. Alleen de gekoppelde UpdateConnectoren kunnen in combinatie met deze app connector worden aangeroepen door een externe applicatie.

  • Op het tabblad Connectoren vind je enkele speciale connectoren. De meestgebruikte is AppConnectorSubject, deze is nodig voor het openen van bijlagen bij dossieritems.
  • Kijk of je nog IP-restricities moet vastleggen.

Filterautorisatie uitdelen voor GetConnectoren:

De GetConnectoren die je via de app connector gaat aanroepen, kunnen alleen records ophalen voor zover dit is toegestaan op basis van de filterautorisatie. Wil je bijvoorbeeld medewerkergegevens ophalen via een app connector, dan moet dit zijn toegestaan op basis van filterautorisatie op medewerker.

Let op:

Richt dit altijd in voordat een app connector op een productieomgeving (of een kopie hiervan) in gebruik wordt genomen. Als er geen filterautorisatie is ingesteld, kan een koppeling via een GetConnector namelijk alle records ophalen, bijvoorbeeld alle medewerkers en hun gegevens.

Autoriseer de gebruikersgroep NIET voor functies (menu-items), tabbladen en acties. Het is immers niet de bedoeling dat via deze gebruikersgroep in Profit gewerkt wordt.

  1. Ga naar: Algemeen / Beheer / App connector.
  2. Op het tabblad Algemeen zie je de gebruikersgroep waarvoor je de filterautorisatie moet instellen.
  3. Ga naar het tabblad: GetConnectoren.
  4. In de eigenschappen van een app connector zie je per GetConnector welke filterautorisatie je kunt toepassen. Dit is nieuw in Profit 9

  5. Ga naar: Algemeen / Beheer / Autorisatie tool.
  6. Ga naar het tabblad: Onderhoud groepen.
  7. Selecteer de gebruikersgroep die aan de app connector gekoppeld is.
  8. Ga naar het tabblad: Autorisatie.
  9. Deel rechten uit op de juiste filters.

Zie ook:

  • Autorisatiefilters toevoegen
  • Gegevensfilter activeren