Inloggen in "Mijn-omgeving" met Club.Dataservice

Privacygevoelige gegevens, zoals persoonsgegevens of financiële gegevens van leden, zijn alleen toegankelijk met een gebruikersnaam en wachtwoord. Artikelen die dit soort gegevens bevatten worden artikelen met een scope genoemd. Om artikelen met een scope te kunnen opvragen, moet je eerst een token verkrijgen. Hiervoor moet de gebruiker jou de toestemming geven om gegevens op te halen met een bepaalde scope. Momenteel implementeert Club.Dataservice de implicit OAuth flow. Om een token te verkrijgen moeten de volgende stappen doorlopen worden:

1. Redirect de gebruiker naar de inlog pagina met een aantal parameters:

https://auth.sportlink.com/oauth?redirect_uri={...}&response_type=token&client_id={...}&scope={...}&state={...}

 

Parameter Uitleg
redirect_uri Waar de response naar moet worden terug gestuurd
response_type Moet "token" zijn om implicit flow aan te tonen
client_id De client identifier van de vereniging
scope Welke scopes je wilt (komma gesplitste lijst)
state Gebruik dit veld om de response te controleren. Club.data stuurt de gegeven waarde weer terug. Wanneer de waardes verschillen invalideert het login proces.
 

Voorbeeld response wanneer de gebruiker heeft ingelogd op auth.sportlink.com:

redirect_uri/#token=gth8kj7lnf0hpn3cc9h13fcesf&token_type=bearer&scope=PERSON&expires_in=3600&state=123123

De response wordt terug gestuurd via de hash, hierdoor weet alleen de browser van het bestaan van deze key values en kan de server er niet bij. Hierdoor moet bij de implicit flow een clientside browser programmeertaal zoals JavaScript gebruikt worden om deze uit te lezen.

 

Response Uitleg
token Token die gebruikt moet worden om data op te halen voor bepaalde scope.
token_type Altijd "bearer"
scope Welke scopes er gevraagd zijn
expires_in Hoelang de token geldig is in seconden
state Gelijk aan de opgegeven state
 

2. Token meegeven

De token moet via de Authorization header worden meegegeven worden. Dit ziet er zo uit:

curl -iG https://data.sportlink.com/mijn-gegevens \
--header "Authorization: Bearer 1cki4ic3u306118ucckjps7pv6"

Errors

Errors worden via the redirect_uri als GET parameters teruggestuurd. Mogelijke error ziet er bijvoorbeeld zo uit:

http://localhost:9090/?error=invalid_scope&error_description=The%20requested%20scope%20is%20invalid,%20unknown,%20or%20malformed.

Mogelijke id's zijn invalid_scope, invalid_request en server_error

Wanneer er iets fout gaat probeert Club.Data een JSON object terug te sturen met hierin informatie over de fout. Over het algemeen krijg je altijd een error in de volgende vorm:

{"error":{"message": "...","code": ...}}

De code staat vast en zal nooit veranderen. De message kan wel veranderen. Dus gebruik de code om te kijken welke error er is opgetreden. Wanneer u geen geldige JSON of een onbekende code als response krijgt, gebruik dan de HTTP status code om uw vervolg actie te bepalen. Mogelijke errors:

 

HTTP Code Code Omschrijving
400 4002 Verplicht argument is niet gegeven (zie list voor welke verplicht zijn)
401 4011 Gegeven token bestaat niet of is ongeldig
401 4012 Gegeven client_id bestaat niet of is ongeldig
403 4031 Token heeft niet de vereiste scopes om het artikel op te vragen
404 4041 Opgevraagde artikel bestaat niet.
500 5001 Server fout. Er gaat iets fout aan onze kant, dit moet onderzocht worden.
 

Let op:

Een zogenoemde condition error volgt een iets ander patroon, namelijk:

{"error":{"messages":[{"id":"...","description":"..."}],"code":4001}}

In plaats van een enkel error bericht, krijg je nu een collectie van error berichten terug.