Inhoud


Introductie

Dit document wordt gebruikt om OAuth 2.0-authenticatie te implementeren voor Deployteq Webhooks.

Stappen:

  • Applicatiebeheerder: Registreer je applicatie bij Deployteq. Dit resulteert in een Client ID en geheime sleutel (client-geheim).
  • Verkrijg een toegangstoken. Ondersteunde grant types  zijn 'Client-inloggegevens' en 'Autorisatiecode'.
  • Configureer je webhook.

Applicatiebeheerder

De eerste stap is om de applicatie te registreren die zal verbinden met Deployteq, dit zal resulteren in een cliënt-id en geheime sleutel.

Als de OAuth 2.0 Server-module is geactiveerd, zie je een nieuw menu-item in Deployteq om al je geïntegreerde OAuth 2.0-applicaties te beheren. Binnen deze interface kunnen gebruikers een overzicht zien van de applicatie die is verbonden met Deployteq via OAuth 2.0-authenticatie en deze bijwerken of verwijderen.

Toevoegen nieuwe applicatie

Ook kunnen nieuwe applicaties worden geregistreerd, wat zal resulteren in een gepersonaliseerde Cliënt-ID en Cliënt-geheim, die kunnen worden gebruikt om een OAuth 2.0-toegangstoken aan te vragen. De volgende informatie wordt gevraagd:

  • Applicatie name
  • Beschrijving
  • Scope (afhankelijk van wat er op het portaal aan staat zie je hier wel of geen mobile inbox opties)
    • Op dit moment worden de volgende scopes ondersteund:
      • Webhooks: apps.webhook:execute
        • Deze scope ondersteunt het uitvoeren van webhooks binnen Deployteq.
      • Offline access: offline_access
        • Offline-toegang is alleen van toepassing op het grant type"Autorisatiecode" en wordt gebruikt voor refresh tokens.
      • Customer: crm.customer:read
      • Inboxes: crm.inbox.inboxes:read
      • Inbox messages: crm.inbox.messages:read crm.inbox.messages:update crm.inbox.messages:delete
  • Redirect URL
    • Voer je eigen redirect-URL in voor de OAuth-stroom. Deze waarde kan ook worden overschreven in de queryreeks bij het aanvragen van een autorisatiecode.


Als alle vereiste informatie is verstrekt en bevestigd, wordt een bevestigingsscherm weergegeven, inclusief de Cliënt-ID en de geheime sleutel (client-geheim).


Client secret

Wees ervan bewust dat het Cliënt-geheim slechts één keer wordt weergegeven. Als je het cliëntgeheim bent kwijtgeraakt, moet je je applicatie opnieuw registreren.

Krijg toegangstoken

Afhankelijk van het gekozen grant type kan een toegangstoken worden verkregen voor communicatie met de webhook. De term "grant type" verwijst naar de manier waarop een applicatie een toegangstoken verkrijgt. OAuth 2.0 definieert verschillende grant types, waaronder de autorisatiecode-stroom. We ondersteunen de grant types "Client Credentials" en "Authorization code", zoals hieronder beschreven.

Client Credentials

Het grant type "Client Credentials" is de simpelste manier om een toegangstoken te krijgen. De volgende informatie is vereist:


Bekijk de twee voorbeeldverzoeken hieronder waarin je een verzoek voor een toegangstoken kunt verzenden:

Request Access token: Client credentials 1
curl -u "{client_id}:{client_secret}" 
     -d "grant_type=client_credentials&scope=apps.webhook:execute" https://auth.clang.cloud/oauth2/token
Request Access token: Client credentials 2
curl --location --request POST 'https://auth.clang.cloud/oauth2/token' \
--header 'Authorization: Basic {Base64 Encoded: "client_id:client_secret"}' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'scope=apps.webhook:execute'


In de reactie ontvang je het toegangstoken en de levensduur van het toegangstoken in Unix-tijd (3600 seconden, wat overeenkomt met 1 uur):

Response example Access Token
{
  "access_token": "{access token}",
  "expires_in": "3600",
  "scope": "apps.webhook:execute",
  "token_type": "bearer"
}


Autorisatie Code

De Autorisatiecode Grant Type is waarschijnlijk de meest voorkomende van de OAuth 2.0 grant types. Het verschilt van de meeste andere grant types doordat het eerst een autorisatiecode vereist, waarna de app een browser opent om het proces te starten voor het verkrijgen van een toegangstoken.

Ontvang gebruikersmachtigingen en ontvang de autorisatiecode.

OAuth draait allemaal om gebruikers in staat stellen beperkte toegang te verlenen aan applicaties. De applicatie moet eerst beslissen welke toestemmingen het aanvraagt en vervolgens de gebruiker naar een browser sturen om hun toestemming te verkrijgen. Om de autorisatiestroom te starten, vervang je je client_id en open je de volgende URL in een browser:

Request authorization code
https://auth.clang.cloud/oauth2/auth?client_id={client_id}&response_type=code&state={state}&scope={scopes}

For example:
https://auth.clang.cloud/oauth2/auth?client_id=a227118e-7c51-4b26-9ae&response_type=code&state=Example12345&scope=apps.webhook:execute


Optional fields

ParamDescription
redirect_uri 

De URL van de callback van de clientapplicatie waarnaar wordt doorgestuurd na authenticatie. Deze moet worden geregistreerd bij de geregistreerde applicatie in Deployteq. Bijvoorbeeld: https://your-application.com/registered/callback

scope

Het bereik van de toegang dat je aanvraagt, dat meerdere waarden gescheiden door spaties kan bevatten.

state

De state-parameter heeft twee functies:

  • Wanneer de gebruiker wordt teruggestuurd naar de app, wordt elke waarde die als state is opgenomen, ook opgenomen in de omleiding. Hierdoor krijgt je app de kans om gegevens te behouden tussen het moment dat de gebruiker naar de autorisatieserver wordt geleid en weer terug, bijvoorbeeld door de state-parameter te gebruiken als een sessiesleutel. Dit kan worden gebruikt om aan te geven welke actie in de app moet worden uitgevoerd nadat de autorisatie is voltooid, bijvoorbeeld aangeven naar welke pagina's van je app moet worden omgeleid na autorisatie.

  • De state-parameter dient ook als een CSRF-beveiligingsmechanisme als deze een willekeurige waarde per verzoek bevat. Wanneer de gebruiker wordt teruggestuurd naar je app, controleer dan dubbel of de waarde van de state overeenkomt met wat je oorspronkelijk hebt ingesteld.


Dit zal de Deployteq toestemmingspagina tonen. Log in met de Deployteq-inloggegevens van de gebruiker die de applicatie binnen Deployteq heeft aangemaakt:


Je moet de inloggegevens van Deployteq gebruiken van dezelfde Deployteq-gebruiker die de applicatie heeft geregistreerd in Deployteq. Na het inloggen zal Deployteq om jouw toestemming vragen voor de gedefinieerde scopes, in dit geval het uitvoeren van webhooks:

Nadat de toestemming voor de scope is verleend, word je omgeleid naar de omleidings-URL zoals gedefinieerd in de applicatie. De omleidings-URL (in de adresbalk van de browser) bevat een autorisatiecode toegevoegd aan de queryreeks:

Response authorization code
https://your-application.com/registered/callback?code={authorization code}&state=Example12345

Time span Authorization code

De autorisatiecode is slechts 60 minuten geldig.

Wissel de autorisatiecode in voor een toegangstoken

Nu je een autorisatiecode hebt, moet je deze inwisselen voor een toegangstoken die kan worden gebruikt om Deployteq webhooks aan te roepen.

Om de OAuth 2.0-flow te voltooien, moeten we de autorisatiecode inwisselen voor een toegangstoken. De volgende informatie is vereist:


Response authorization code
curl -u "{client_id}:{client_secret}" 
     -d "grant_type=authorization_code&code={Authorization_code}" https://auth.canopydeploy.net/oauth2/token
Request Access token: Client credentials 2
curl --location --request POST 'https://auth.deployteq.net/oauth2/token' \
--header 'Authorization: Basic {Base64 Encoded: "client_id:client_secret"}' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=authorization_code' \
--data-urlencode 'code={Authorization_code}'
Response example Access Token
{
  "access_token": "{access token}",
  "expires_in": "3600",
  "scope": "apps.webhook:execute",
  "token_type": "bearer"
}

Configureer je webhook

Als je het toegangstoken hebt opgehaald, kun je dit gebruiken om Deployteq-webhooks aan te roepen. Stel eerst een nieuwe webhook in vanuit de Deployteq-winkel:

In de installatiewizard van webhooks is de tweede stap waar je de authenticatie op OAuth 2.0 instelt. Kopieer eenvoudig het endpoint en gebruik dit om het eerste verzoek te verzenden.

Zie het voorbeeld hieronder:

Request Access token: Client credentials 2
curl --location --request POST '{endpoint}' \
     --header 'Authorization: Bearer {Access Token}' \
     --header 'Content-Type: application/json' \
     --data-raw '{
       "firstname": "Oauth",
       "email": "oauth2@deployteq.com"
      }'

Voor meer informatie over webhooks en configuratie, zie deze handleiding.

Postman gebruiken

Je kunt ook Postman gebruiken om OAuth 2.0 autorisatietokens te verkrijgen.

Postman - Client Credentials

Bekijk het onderstaande voorbeeld op basis van het grant type "Clientgegevens" (Client Credentials):


Als het token met succes is aangevraagd, zal Postman een bevestigingsscherm tonen met het vereiste toegangstoken.


Postman - Autorisatie Code

Bekijk het onderstaande voorbeeld op basis van het grant type "Autorisatiecode":

Return URL Postman

Postman genereert zijn eigen retour-URL, die moet worden opgenomen in de registratie van jouw applicatie in Deployteq.

Wanneer je een token aanvraagt in Postman, zal Postman je doorsturen naar je standaardwebbrowser

En je toestemming vragen:


Browser Pop-ups

Let op dat pop-ups moeten worden toegestaan op deze pagina om het toegangstoken terug te kunnen ontvangen in Postman.


Als de toestemming succesvol was, zal je een bevestigingspagina zien: