OAuth2 koppelingen met Copernica

OAuth 2.0 is een protocol waarmee je veilig toegang kunt krijgen tot gegevens van andere accounts zonder dat gebruikers hun wachtwoord hoeven te delen. Met OAuth2 vraag je mensen om toestemming om hun gegevens met jouw integratie te delen.

Gebruik OAuth2 als je een applicatie wilt koppelen aan Copernica-accounts waar je zelf geen toegang toe hebt. Door een button op je website te plaatsen, kunnen gebruikers jouw applicatie eenvoudig toegang verlenen tot hun Copernica-data.

Hoe werkt dit voor gebruikers?

Een OAuth handshake ziet er in het kort als volgt uit:

De gebruiker is eerst op jouw website. Hier leg je uit hoe jouw tool of integratie werkt, en dat je hiervoor toegang tot een Copernica-account nodig hebt. Op deze pagina staat een button of link om een koppeling te maken. Let op: je mag een gebruiker niet dwingen om een koppeling te maken, dit moet vrijwillig gebeuren.

De gebruiker klikt op de button. Als de gebruiker inderdaad een account wil openstellen voor jouw applicatie, dan wordt hij of zij doorgestuurd naar de Copernica website, en om akkoord gevraagd om gegevens te delen.

De gebruiker keert terug naar jouw website. Na akkoord op de Copernica website, keert de gebruiker terug naar jouw website, en via een handshake achter de schermen kan jouw website nu het API token ophalen om toegang tot het account te krijgen. De gebruiker krijgt te zien dat de koppeling is geslaagd.

Stappenplan voor ontwikkelaars

Om de OAuth handshake te faciliteren, moet je jouw applicatie aanmelden bij Copernica, en daarna een paar pagina's toevoegen aan je website waarin je uitleg geeft over de koppeling. Ook moet je een HTTP GET request sturen vanuit jouw webserver naar Copernica om het token op te halen.

Stap 1 applicatie aanmelden in Marketing Suite:

  • Meld je applicatie aan via de configuratie-module in Marketing Suite, onder het kopje "API applicaties".
  • Geef een duidelijke naam en omschrijving op.
  • Na aanmelding ontvang je een client_key en client_secret. Bewaar deze gegevens veilig.
  • Deze link plaats je op de pagina waar de gebruiker wordt gevraagd om toegang te verstrekken.
  • De link stuurt gebruikers naar Copernica.com om in te loggen en toegang te verlenen.
  • Gebruik deze URL: https://www.copernica.com/nl/authorize?client_id=XXX&redirect_uri=XXX&state=XXX&response_type=code
  • Vervang de XXX-waarden met je eigen gegevens:
    • client_id: jouw client_key.
    • redirect_uri: het adres van de terugkeerpagina op je website (zie hieronder).
    • state: een unieke, steeds wisselende, moeilijk te raden en willekeurige gegenereerde string.
    • response_type: de string "code".

Stap 3: ontwikkel een terugkeerpagina

Deze pagina wordt bezocht als de koppeling tot stand is gebracht. Als de pagina wordt bezocht, moet je op de webserver het volgende doen:

  • Controleer of aan de URL van de pagina de parameters state en code zijn toegevoegd.
  • Controleer of de state overeenkomt met de oorspronkelijke waarde.
  • Gebruik de code om een access token op te halen (zie hieronder).

Omdat de state in stap 2 wordt gegenereerd, en in stap 3 moet worden gecontroleerd, is het gebruikelijk deze variabele op te slaan in de sessie of in een cookie.

Stap 4: ophalen van het API access token

Let op: deze URL moet je niet aan de gebruiker tonen, en je hoeft hem of haar er ook niet naar door te verwijzen. Het is de bedoeling dat je vanaf jouw server een HTTP GET request naar dit adres stuurt.

Stap 5: ophalen van API access token

Als alles goed gaat, ontvang je bij stap 4 een JSON document met een access_token. Dit is het API access token.

{ "access_token" : "ed230a95c58fd7d130c9db453396cf5" }

Dit token geeft nog niet rechtstreeks toegang tot de API, maar kun je vervolgens inwisselen voor een API authorization token. Lees meer over authoritzation tokens.