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).

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:

• Toegangsstoken URL: https://auth.clang.cloud/oauth2/token
• Client ID
• Client secret
• Scope
• Client Authenticatie (verzenden als Basic Auth headers)

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

curl -u "{client_id}:{client_secret}" 
     -d "grant_type=client_credentials&scope=apps.webhook:execute" https://auth.clang.cloud/oauth2/token

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):

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

Autorisatie Code

The Autorisatie Code Grant Type is probably the most common of the OAuth 2.0 grant types. It differs from most of the other grant types by first requiring an authorization code and then the app launches a browser to start the flow for requiring an Access token. 

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:

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

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:

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

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:

• Autorisatie URL
  • https://auth.clang.cloud/oauth2/auth
• Access token URL
  • https://auth.clang.cloud/oauth2/token
• Client ID
• Client secret
• Scope
  • Bijvoorbeeld: apps.webhook.execute
• Authorisatie code
  • De applicatie dient de ontvangen autorisatiecode op te nemen in de redirect
• Redirect_uri
  • Dezelfde redirect URL die werd gebruikt bij het aanvragen van de code

curl -u "{client_id}:{client_secret}" 
     -d "grant_type=authorization_code&code={Authorization_code}" https://auth.canopydeploy.net/oauth2/token

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}'

{
  "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:

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":

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

En je toestemming vragen:

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