Authentification

Documentation du flow OAuth "Authorization Code Grant"

Dokeop utilise OAuth2 comme méthode d'authentification. OAuth permet aux applications externes de demander l’autorisation des données d’un utilisateur. Il permet aux utilisateurs d’accorder et de révoquer l’accès à l’API pour chaque application et de protéger les informations d’authentification des utilisateurs.

Tous les développeurs doivent enregistrer leur application avant de commencer. Une application enregistrée se verra attribuer un client_id et client_secret. Le secret est utilisé pour l'authentification et ne devrait jamais être partagé.

Vue d'ensemble d'OAuth

Une fois qu'une demande d'accès OAuth est initiée, l'utilisateur est invité par l'application à se connecter au site Web de Dokeop et à donner son consentement à la demande d'accès pour les portées (scopes) indiquées. Un utilisateur ne peut pas choisir les portées à autoriser pour l'application. Soit il accepte l'ensemble des portées souhaitées ou refuse totalement l'accès à ses données.

Une fois que l'utilisateur a accepté ou rejeté la demande d'autorisation, Dokeop le redirige vers une URL spécifiée par l'application. Si l'utilisateur a autorisé l'application, l'URL de la requête comprendra en paramètre un code d'autorisation (authorization_code ainsi que les portées associées autorisées par l'utilisateur. L'application doit terminer le processus d'authentification en échangeant le code d'autorisation contre un jeton d'actualisation (refresh_token) et un jeton d'accès de courte durée (access_token).

Les applications utilisent les jetons d'accès pour obtenir et modifier les ressources Dokeop pour le compte de l'utilisateur authentifié. Les jetons d'actualisation sont utilisés pour obtenir de nouveaux jetons d'accès lorsque les plus anciens arrivent à expiration.

Demande d'accès

Pour initier une demande d'accès, les applications doivent rediriger l’utilisateur vers la page d’autorisation de Dokeop :

GET https://developers.dokeop.com/oauth/authorize

Details sur la demande d'accès

Sur la page Web, la page d'autorisation invite l'utilisateur à autoriser votre application à accéder à ses données. Les portées demandées par l'application sont affichées.

client_id
required integer, in query 		L'identifieur unique de l'application, obtenu lors de sa création.
redirect_uri
required string, in query 		URL vers laquelle l'utilisateur sera redirigé après l'authentification. Doit être dans la liste des URLS de redirection spécifiées par l'application. localhost et 127.0.0.1 sont autorisées.
response_type
required string, in query 		Doit être code.
scope
required string, in query

Portées demandées, sous forme de chaîne délimitée par des espaces, par exemple "read+write" Les applications ne doivent demander que les étendues requises pour que l'application fonctionne normalement.

  • profile:read: Read your profile information. (profils athlète, organisateur ou plateforme)
  • event:read: Read your event, race and registration data. (profil organisateur seulement)
  • event:write: Create and edit events, races and registrations. (profil organisateur seulement)
  • club_section:read: List the sections of your club and list license applications. (profil club seulement)
  • club_section:write: Create and modify license requests for your club's sections. (profil club seulement)
  • webhook:write: Read, create or delete application webhook subscription. (profil plateforme seulement)
state
string, in query 		Chaîne de caractères libre renvoyée dans l'URL de redirection. Utile si l'authentification est effectuée à partir de différents endroits d'une application pour continuer un workflow sur cette dernière.
role
string, in query 		Rôle de l'utilisateur pour lequel on veut obtenir un access_token. Les valeurs possibles sont platform, organizer, club ou athlete.
locale
string, in query 		Langue d'affichage de l'interface de demande d'autorisation. Les valeurs possibles sont fr ou en.

Échange de jeton

Dokeop répondra à la demande d'autorisation en redirigeant le navigateur vers l'URL de redirection (redirect_uri) fournie.

Si l'accès est refusé, error=access_denied sera inclus en paramètre de l'URL.

Si l'accès est accepté, code et scope seront inclus en paramètre de l'URL. Le paramètre code contient le code d'autorisation requis pour terminer le processus d'authentification. L'application doit maintenant appeler POST https://developers.dokeop.com/oauth/token avec son client_id et son client_secret pour échanger le code d'autorisation contre un jeton d'actualisation et un jeton d'accès de courte durée.

Le paramètre state sera toujours inclus dans la réponse s'il a été fourni initialement par l'application.

client_id
required integer, in query 		L'identifieur unique de l'application, obtenu lors de sa création.
client_secret
required string, in query 		Le secret de l'application, obtenu lors de sa création.
code
required string, in query 		Le paramètre code obtenu dans la redirection.
grant_type
required string, in query 		Le type de demande d'autorisation. Pour l'authentification initiale, il doit toujours s'agir de authorization_code.

Un jeton d'actualisation, un jeton d'accès et une délai d'expiration du jeton d'accès seront émis en cas d'authentification réussie. Le champ expires_in contient le nombre de secondes à partir de la date de création après lesquelles le jeton d'accès fourni expirera.

Exemple de réponse
{
  "token_type": "Bearer",
  "access_token": "987654321234567898765432123456789",
  "refresh_token": "1234567898765432112345678987654321",
  "scope": "profile:read",
  "created_at": 1561559996,
  "expires_in": 28800,
  "state": "DOKEOP"
}

Réactualiser un jeton d'accès expiré

Les jetons d'accès expirent 8 heures après leur création. Ils doivent donc être actualisés pour qu'une application puisse conserver l'accès aux ressources d'un utilisateur. Les applications utilisent le jeton d'actualisation de l'authentification initiale pour obtenir de nouveaux jetons d'accès.

Pour actualiser un jeton d’accès, les applications doivent appeler POST https://developers.dokeop.com/oauth/token, en spécifiant grant_type: refresh_token et en incluant le jeton d'actualisation de l’application pour l’utilisateur.

Un jeton d'actualisation est renvoyé à l'application après chaque demande réussie adressées à POST https://developers.dokeop.com/oauth/token. Le jeton d'actualisation peut ou non être le même que celui utilisé pour effectuer la demande. Les applications doivent conserver le jeton d'actualisation contenu dans la réponse et utiliser toujours le dernier jeton d'actualisation pour les demandes suivantes afin d'obtenir un nouveau jeton d'accès. Une fois qu'un nouveau jeton d'actualisation est renvoyé, l'ancien jeton d'actualisation est immédiatement invalidé.

client_id
required integer, in query 		L'identifieur unique de l'application, obtenu lors de sa création.
client_secret
required string, in query 		Le secret de l'application, obtenu lors de sa création.
grant_type
required string, in query 		Le type de demande d'autorisation. Pour l'actualisation d'un jeton d'accès, il doit toujours s'agir de refresh_token.
refresh_token
required string, in query 		Le jeton d'actualisation obtenu pour cet utilisateur, à utiliser pour obtenir le prochain jeton d'accès pour cet utilisateur.
Exemple de réponse
{
  "token_type": "Bearer",
  "access_token": "987654321234567898765432123456789",
  "refresh_token": "1234567898765432112345678987654321",
  "created_at": 1561559996,
  "expires_in": 28800
}

Accéder à l'API en utilisant un jeton d'accès

Les applications utilisent des jetons d’accès non expirés pour adresser des demandes de ressources à l’API Dokeop pour le compte de l’utilisateur. Les jetons d'accès sont obligatoires pour toutes les demandes de ressources et peuvent être inclus en spécifiant l'en-tête Authorization: Bearer #{access_token}.

Par exemple en utilisant HTTPie: 

$ http https://developers.dokeop.com/api/v1/athlete 'Authorization: Bearer 38cfadf160d50f52c89165b7f71ba0d9b71fa4b4cca0349861eed96b0f677dd7'

Révoquer une autorisation

Les applications peuvent révoquer l’accès aux données d’un utilisateur. Cela invalidera tous les jetons d'actualisation et les jetons d'accès que l'application a pour l'utlisateur, et l'application sera supprimée de sa page de paramètres d'applications. Toutes les demandes effectuées à l'aide de jetons invalidés recevront une réponse 401 Non autorisé.

Le point d'entrée est POST https://developers.dokeop.com/oauth/revoke.

client_id
required integer, in query 		L'identifieur unique de l'application, obtenu lors de sa création.
client_secret
required string, in query 		Le secret de l'application, obtenu lors de sa création.
token
required string, in query 		Le jeton d'actualisation ou le jeton d'accès obtenu pour cet utilisateur.

L'API retourne un objet vide dans tous les cas.

Exemple de réponse
{}