Connected Applications (OAuth 2.0-integraties) gaan een steeds belangrijker onderdeel vormen van veel TOPdesk-omgevingen. Naarmate meer processen en applicaties hiervan afhankelijk worden, neemt ook de impact van een verlopen client secret toe.

Wanneer een client secret van een System- of User integration verloopt, kan de gekoppelde integratie onverwacht stoppen met functioneren. Dit kan direct gevolgen hebben voor de bedrijfsvoering: processen kunnen stilvallen, gebruikers kunnen functionaliteit verliezen en het troubleshooten van de oorzaak kan aanzienlijk langer duren. Zeker wanneer niet direct duidelijk is dat een verlopen OAuth-client de oorzaak is, kan kostbare tijd verloren gaan aan het onderzoeken van andere mogelijke oorzaken.

Een goed voorbeeld hiervan is de nieuwe Microsoft Teams-integratie van TOPdesk. Met deze integratie kunnen gebruikers rechtstreeks vanuit Microsoft Teams incidenten aanmaken en bestaande calls bijwerken in TOPdesk. De integratie maakt hierbij gebruik van een OAuth-verbinding, waarbij het client secret van de integration client na één jaar verloopt. Als dit secret niet tijdig wordt vervangen, kan de integratie niet langer functioneren.

Om dit soort verstoringen te voorkomen, heb ik een actiereeks gemaakt die automatisch controleert welke OAuth 2.0-integraties binnenkort verlopen. Afhankelijk van de configuratie kan de actiereeks vervolgens een e-mail versturen en/of automatisch een incident aanmaken.

In deze topic leg ik uit hoe de actiereeks is opgebouwd en hoe je deze kunt configureren.

Let op!

Deze actiereeks maakt gebruik van ongedocumenteerde API-endpoints van TOPdesk. Deze endpoints zijn niet officieel gedocumenteerd of gegarandeerd door TOPdesk en kunnen zonder voorafgaande aankondiging worden gewijzigd of verwijderd.

Hierdoor bestaat het risico dat de actiereeks na een wijziging in TOPdesk niet meer (correct) functioneert. Controleer daarom regelmatig of de actiereeks nog naar behoren werkt, met name na updates of wijzigingen aan de TOPdesk-omgeving.

Wat doet de actiereeks?

De actiereeks controleert zowel:

• User Delegated integrations
• Application integrations

Voor beide typen wordt de expiryDate gecontroleerd. Je bepaalt zelf hoeveel dagen vóór het verlopen een melding moet worden gegenereerd.

Bijvoorbeeld:

expiresInDays = 30

Dan worden alle integrations geselecteerd waarvan de expiry date binnen de komende 30 dagen valt.

De actiereeks kan vervolgens:

• een e-mail sturen naar een configureerbaar e-mailadres;
• een TOPdesk-incident aanmaken;
• of beide acties uitvoeren;

Overzicht van de actiereeks

De actiereeks bestaat in hoofdlijnen uit de volgende stappen:

1. Bepalen van de controleperiode.
2. Ophalen van User Delegated integrations.
3. Doorlopen en controleren van iedere User integration.
   1. Eventueel een e-mail versturen.
   2. Eventueel een incident aanmaken.
4. Ophalen van System Delegated integrations.
5. Doorlopen en controleren van iedere System integration.
   1. Eventueel een e-mail versturen.
   2. Eventueel een incident aanmaken.

1. De controleperiode bepalen

Als eerste wordt op basis van de variable expiresInDays bepaald vanaf welke datum integrations als "bijna verlopen" worden beschouwd. De variable bepaalt dus hoeveel dagen vooruit wordt gekeken.

Voorbeeld:

De berekende datum wordt intern opgeslagen in de variable notBefore.

2. User Delegated integrations ophalen

Daarna wordt via de Integration Client Management API een overzicht opgehaald van de User integrations.De actiereeks gebruikt hiervoor:

services/integration-client-management/userIntegrations

Vervolgens wordt iedere gevonden integration afzonderlijk gecontroleerd.

3. User integrations controleren

Voor iedere User Delegated integration wordt de expiry date vergeleken met de eerder berekende controleperiode. Wanneer de integration binnen de ingestelde periode verloopt, wordt het aantal resterende dagen berekend en opgeslagen in: daysBeforeExpire

De e-mail en het eventuele incident bevatten vervolgens onder andere:

• naam van de integration;
• Client ID;
• expiry date;
• creation date;
• created by;
• de geconfigureerde Redirect URI's.

3.1. E-mailnotificatie

Wanneer sendMail is ingesteld op true, wordt voor iedere integration die binnen de ingestelde periode verloopt een e-mail verstuurd. De afzender en ontvanger worden bepaald door:

• mailFrom
• mailTo

Wanneer sendMail op false staat, wordt deze stap overgeslagen.

Dit maakt het bijvoorbeeld mogelijk om de actiereeks eerst alleen te gebruiken voor incidentregistratie, zonder e-mails te versturen.

3.2. Automatisch een incident aanmaken

Je kunt er ook voor kiezen om automatisch een TOPdesk-incident aan te maken. Hiervoor moet:

createIncident = true zijn ingesteld.

De actiereeks vult het incident automatisch met informatie over de betreffende integration. Daarnaast kun je via de variables bepalen onder welke caller, categorie, subcategorie, operator en operatorgroep het incident wordt aangemaakt.

Per integration wordt slechts één incident aangemaakt. De actiereeks gebruikt hiervoor het externalNumber-veld van het incident. Hierin wordt het unieke ID van de betreffende integration opgeslagen. Bij een volgende controle kan de actiereeks hierdoor herkennen dat er al een incident voor deze integration bestaat en wordt er geen nieuw incident aangemaakt.

Je wordt hierdoor dus niet overspoeld met meerdere incidenten voor dezelfde integration. Zodra er al een incident voor de betreffende integration bestaat, wordt er geen nieuw incident aangemaakt.

4. Application integrations

Na het controleren van de User integrations wordt hetzelfde principe toegepast op Application integrations.

Deze worden opgehaald via:

services/integration-client-management/systemIntegrations

Ook hier wordt iedere integration gecontroleerd op basis van de ingestelde expiresInDays.

5. Application integrations controleren en rapporteren

Voor iedere Application integration die binnen de controleperiode verloopt, wordt daysBeforeExpire berekend. Afhankelijk van de configuratie wordt vervolgens:

• een e-mail verstuurd;
• een incident aangemaakt;
• beide gedaan;
• of niets gedaan.

De incident- en e-mailinformatie bevat onder andere de naam, Client ID, creation date en created by.

Configuratie van de variables

De actiereeks bevat de volgende variables:

Voor sendMail en createIncident moeten de waarden als tekst worden opgegeven:

• true
• false

De overige waarden moeten overeenkomen met de gegevens die in de betreffende TOPdesk-omgeving beschikbaar zijn. De actiereeks bevat deze variables als configureerbare invoer.

Flexibel in gebruik

Een voordeel van deze opzet is dat de actiereeks niet verplicht één specifieke manier van notificeren gebruikt. Je kunt bijvoorbeeld kiezen voor:

Alleen e-mail

sendMail = true
createIncident = false

Alleen incidenten

sendMail = false
createIncident = true

E-mail én incident

sendMail = true
createIncident = true

Tot slot

Met deze actiereeks kun je het verlopen van OAuth 2.0 integrations proactief monitoren, zonder dat je handmatig alle Application en User integrations hoeft te controleren.

Door de controleperiode en de notificatieopties via variables configureerbaar te maken, kan dezelfde actiereeks eenvoudig worden aangepast aan de werkwijze van verschillende TOPdesk-omgevingen.

De actiereeks is opgezet rond de TOPdesk Integration Client Management API en de TOPdesk Incident API. De daadwerkelijke API-calls voor User en System integrations en het aanmaken van incidents zijn onderdeel van de actiereeks.