OAuth2 est utilisé comme infrastructure d'authentification et d'autorisation pour API v2. En bref, chaque demande d'API nécessite un en-tête d'autorisation contenant votre jeton d'accès OAuth2. Nous expliquerons à quoi cela ressemble et quelles sont les possibilités.
Fonctionnalités principales
- OAuth2 est utilisé pour l'authentification et l'autorisation
- Créez des jetons personnels pour vous authentifier avec un jeton au lieu d'un mot de passe
- La durée de vie du jeton est de 14 jours par défaut, avec un maximum de 90 jours.
- Chaque demande d'API nécessite un en-tête d'autorisation
Ce qu'il vous faut pour réussir
Voici ce dont vous avez besoin pour utiliser l'API REST Showpad :
- Plan tarifaire ultime de Showpad
- Accès à Showpad Online Platform
- Connaissance de base de REST
- Connaissance de base de JSON
Un moyen rapide pour atteindre des choses géniales.
- En-tête de la clé API
- Clients OAuth
- Jetons personnels
- Portées Client
- Flux côté serveur
- L'identité de l'utilisateur demandant l'autorisation est vérifiée
- L'autorisation du client est vérifiée
- Vérifier l'identité du client
- Réponse du jeton d'accès
- Actualiser le flux de jetons
- Flux d'informations d'identification de l'utilisateur
- Réponse du jeton d'accès
L'obtention d'un jeton d'accès peut être effectuée à l'aide du flux côté serveur, du flux de régénération du jeton ou des flux d'informations d'identification utilisateur. Chaque flux est traité en détail dans une Section ultérieure de ce document.
Autorisation : porteur myOAuth2AccessToken |
Dans OAuth2, chaque application qui se connecte à l'API Showpad est définie en tant que client. Chaque client doit être enregistré sur Showpad afin de fournir un niveau de confiance. Un paramètre important du client est son URL de rappel. Cette URL est utilisée lors de l'obtention d'un jeton d'accès mais constitue également un moyen d'authentifier le client.
Vous pouvez enregistrer un client OAuth2 via la Section API qui se trouve dans les paramètres d'administrateur de votre compte Showpad.
- Choisissez Gérer les clients OAuth.
- Cliquez sur + pour ajouter un client OAuth2.
- Entrez les détails de votre client, définissez la portée (pour plus d'informations, voir "Portées du client" ci-dessous), puis appuyez sur Ajouter.
- Vous pouvez modifier la durée de vie par défaut du jeton sur 90 jours. Par défaut, le paramètre est défini sur 14 jours.
Les jetons d'accès personnel vous permettent de vous authentifier avec l'API Showpad si vous utilisez un mot de passe.
Dans les paramètres API de la Online Platform, vous pouvez nommer votre jeton et lui attribuer une date d'expiration.
- Accédez à l'onglet API dans les paramètres de l'administrateur.
- Donnez un nom à votre jeton et définissez une date d'expiration.
- Copiez le jeton et utilisez-le dans votre application. Ce jeton ne s'affiche qu'une fois et vous ne pouvez pas le récupérer plus tard. Rangez-le dans un endroit sûr pour une utilisation future. Cliquez sur Terminé.
- Pour révoquer l'accès, appuyez sur Révoquer.
Chaque client est également caractérisé par ses portées. Une étendue est un ensemble d'autorisations client permettant d'accéder à certaines ressources. Par exemple, la portée read_user_management donne au client l'accès aux données utilisateur en lecture (et uniquement en lecture). Le tableau ci-dessous répertorie toutes les portées.
| Portée | Description |
|---|---|
| refresh_token | Actualiser le jeton d'accès à l'aide d'un jeton d'actualisation |
| read_user_management | Lire les données utilisateur (comprend les utilisateurs, les groupes d'utilisateurs et les autorisations utilisateur) |
| write_user_management | Écrire des données utilisateur (comprend les utilisateurs, les groupes d'utilisateurs et les autorisations utilisateur) |
| read_contentprofile_management |
Lire les ressources liées au profil de contenu (profils de contenu, ressources, tags, tickets et Commentaires) |
| write_contentprofile_management | Écrire des ressources liées au profil de contenu (profils de contenu, ressources, tags, tickets et Commentaires) |
| read_division_management | Lire les ressources liées aux divisions (divisions et autorisations de division) |
| write_division_management | Écrire des ressources liées aux divisions (divisions et autorisations de division) |
Lorsque vous parlez des portées, il est important de comprendre que chaque utilisateur doit autoriser le client à autoriser ces portées. Ceci est davantage illustré dans le flux d'authentification ci-dessous. Lorsqu'un client modifie ses étendues, toutes les autorisations et tous les jetons d'accès sont révoqués, ce qui oblige chaque utilisateur à autoriser à nouveau son client sur l'accès à l'API.
L'application client contacte le point de terminaison Authorize du Showpad. L'accès au noeud final doit être effectué via GET https://my-subdomain.showpad.biz/api/v2/oauth2/authorize. Trois paramètres de requête sont nécessaires et ils doivent être envoyés en tant que paramètres URL :
Cliquez ici pour ouvrir le diagramme dans une fenêtre séparée.
| Paramètre | Champs obligatoires. | Description |
|---|---|---|
| identité du client | Oui | L'ID de votre client OAuth2 tel qu'il est obtenu à partir de Online Platform. |
| redirect_uri | Oui | L'URL de rappel, appelée après une demande d'autorisation réussie. Cette URL doit être spécifiée lors de l'enregistrement du client OAuth2. |
| type_réponse | Oui | Cela devrait être "code" pour ce flux d'authentification |
| Etat | non | Données supplémentaires codées en URL qui seront renvoyées via l'URL de rappel |
| portée | non | Spécifiez les portées auxquelles cette demande doit être limitée. Vous ne pouvez pas spécifier une étendue que le client n'est pas autorisé à utiliser. Pour plus d'informations, voir portées client |
L'identité de l'utilisateur demandant l'autorisation est vérifiée
Cliquez ici pour ouvrir le diagramme explicatif dans une fenêtre séparée.
- Si l'utilisateur est déjà connecté, il est redirigé vers le composant d'autorisation du client (étape 3).
- Si l'utilisateur n'est pas connecté, il lui sera demandé de saisir ses informations d'identification. L'utilisateur sera redirigé vers https://my-subdomain.showpad.biz/login.
- Une fois ses informations d'identification saisies, Showpad vérifie l'identité.
- Une fois l'identité vérifiée, le client peut être autorisé (étape 3).
L'autorisation du client est vérifiée
Cliquez ici pour ouvrir le diagramme explicatif dans une fenêtre séparée.
- Si le client avait déjà été autorisé par l'utilisateur dans le passé, un code d'autorisation temporaire sera créé et renvoyé au client via l'étape 4.
- Si le client n'a pas encore été vérifié par l'utilisateur, celui-ci sera transféré sur une page d'autorisation du client. Ici, l'utilisateur pourra voir une description du client avec lequel il se connecte. Il devra également accepter l'ensemble des portées requises par le client.
- Si le client est d'accord avec les exigences du client, un code d'autorisation temporaire est généré.
- Si le client n'accepte pas les exigences du client, le processus d'autorisation ne peut pas continuer.
- L'utilisateur sera redirigé vers l'URL de redirection, comme indiqué à l'étape 1. Il contiendra 2 paramètres de requête.
| Paramètre | Description |
|---|---|
| code | Le code d'autorisation à utiliser à l'étape 5. Ce code n’est valide que pendant 30 secondes. Par conséquent, assurez-vous d’échanger le code d’autorisation contre un jeton d’accès le plus rapidement possible à l'étape 5. |
| Etat | L'état envoyé en tant que paramètre à l'étape 1 |
L'application client demande un jeton d'accès via POST https://my-subdomain.showpad.biz/api/v2/oauth2/token. Les paramètres suivants doivent être ajoutés dans le corps du POST. La demande doit être authentifiée avec HTTP Basic à l'aide de l'ID client et du secret client.
| Paramètre | Champs obligatoires. | Description |
|---|---|---|
| grant_type | Oui | Cela devrait être autorisation_code pour ce flux d'authentification |
| code | Oui | Le code d'autorisation tel que récupéré à l'étape 4 |
| redirect_url | Oui | URL de rappel utilisée à l'étape 1 et spécifié lors de l'enregistrement du client OAuth2 |
| Etat | non | Données supplémentaires encodées en URL qui seront retournées |
Cliquez ici pour ouvrir le diagramme explicatif dans une fenêtre séparée.
- Si le client a transmis l'ID et le secret corrects via HTTP de base, le code d'autorisation et l'ours de rappel sont vérifiés comme indiqué à l'étape 7.
- Si le client a transmis une combinaison ID / secret incorrecte, le flux d'authentification s'arrête.
Vérifiez le code d'autorisation et l'URL de rappel. Le code n’est valide que pendant 30 secondes. Assurez-vous d’échanger le code d’autorisation contre un jeton d’accès le plus rapidement possible à l'étape 5.
- Si le code d'autorisation et l'URL de rappel sont valides, un jeton d'accès et d'actualisation est créé à l'étape 8.
- Si le code d'autorisation et / ou l'URL de rappel ne sont pas valides, le flux d'authentification s'arrête.
Les jetons d'accès et d'actualisation sont renvoyés au client. Vous trouverez ci-dessous un exemple de réponse.
{
"access_token" : "3eb33bef34d208479d5ee291307c330864b40e87",
"expires_in":3600,
"token_type" : "Bearer",
"scope" : "refresh_token read_user_management write_user_management
read_contentprofile_management write_contentprofile_management
read_division_management write_division_management ",
"refresh_token" : "7196116f9a1d56411b8fe621d4afda9b9eb4ae93"
}
|
| Paramètre | Description |
|---|---|
| access_token | Le jeton d'accès qui vous accordera l'accès aux ressources protégées. Ajoutez-le à la demande via l'en-tête Authorization sous la forme : Bearer myAccessToken. |
| expire dans | Nombre de secondes après l'expiration du jeton d'accès (1 heure ou 3600 secondes par défaut) |
| type de jeton | Porteur |
| portée | Une Collection de portées délimitées par l’espace que ce jeton d'accès peut être utilisée pour : |
| refresh_token | Ce jeton peut être utilisé pour obtenir un nouveau jeton d'accès (par exemple, lorsque le jeton a expiré). Ce jeton d'actualisation n'est valide qu'une seule fois et sera remplacé lorsqu'un nouveau jeton d'accès est obtenu. |
Le client peut maintenant accéder à l'API Showpad. Il suffit d'ajouter le jeton d'accès à l'en-tête Authorization sous la forme : Bearer myAccessToken
Le service Showpad répondra avec
- un 401 si votre jeton d'accès est invalide.
- un 403 si votre jeton d'accès est valide, mais que vous n'avez pas accès à la ressource demandée.
Un jeton d'accès expire généralement une heure après son obtention. Lorsqu'un jeton d'accès a expiré, vous pouvez obtenir un nouveau jeton d'accès via le flux de jetons d'actualisation. Après l'actualisation du jeton d'accès, vous recevrez un nouvel accès et un jeton d'actualisation.
Les étapes suivantes sont nécessaires pour actualiser un jeton d'accès.
L'application client demande un jeton d'accès via POST https://my-subdomain.showpad.biz/api/v2/oauth2/token. Les paramètres suivants doivent être ajoutés au corps du POST. La demande doit être authentifiée avec HTTP Basic en utilisant l'ID client en tant que nom d'utilisateur et le secret client en tant que mot de passe.
| Paramètre | Champs obligatoires. | Description |
|---|---|---|
| grant_type | Oui | Cela devrait être refresh_token pour ce flux d'authentification |
| refresh_token | Oui | Le jeton d'actualisation obtenu à partir de la demande de flux d'authentification (étape 8) |
| Etat | non | Données supplémentaires codées en URL qui seront renvoyées |
Les jetons d'accès et d'actualisation sont renvoyés au client. Vous trouverez ci-dessous un exemple de réponse.
Réponse du jeton d'accès
{
"access_token" : "3eb33bef34d208479d5ee291307c330864b40e87",
"expires_in":3600,
"token_type" : "Bearer",
"scope" : "refresh_token read_user_management write_user_management
read_contentprofile_management write_contentprofile_management
read_division_management write_division_management ",
"refresh_token" : "7196116f9a1d56411b8fe621d4afda9b9eb4ae93"
}
|
Remarque : Un jeton d'actualisation est généralement valide pendant 14 jours. Après 14 jours, vous devez répéter le flux d'authentification pour obtenir un jeton d'accès.
Flux d'informations d'identification de l'utilisateur
Showpad fournit également un moyen d'obtenir un jeton d'accès et d'actualisation à l'aide du nom d'utilisateur et du mot de passe de l'utilisateur. Ce flux est appelé le flux d'informations d'identification d'utilisateur (propriétaire de la ressource) et est généralement utilisé dans les cas où il existe un niveau de confiance élevé entre le client et l'utilisateur.
Les étapes suivantes sont nécessaires pour obtenir un jeton d'accès :
L'application client demande un jeton d'accès via POST https://my-subdomain.showpad.biz/api/v2/oauth2/token. Les paramètres suivants doivent être ajoutés dans le corps du POST. La demande doit être authentifiée avec HTTP Basic en utilisant l'ID client en tant que nom d'utilisateur et le secret client en tant que mot de passe.
| Paramètre | Champs obligatoires. | Description |
| grant_type | Oui | Cela devrait être "mot de passe" pour ce flux d'authentification |
| nom d'utilisateur | Oui | Le nom d'utilisateur de l'utilisateur pour lequel vous souhaitez obtenir un jeton d'accès |
| mot de passe | Oui | Le mot de passe de l'utilisateur pour lequel vous souhaitez obtenir un jeton d'accès |
| Etat | non | Données supplémentaires codées en URL qui seront renvoyées |
| identité du client | Oui | Les paramètres peuvent être trouvés dans l'OP après la création du client OAuth |
| client_secret | Oui | Les paramètres peuvent être trouvés dans l'OP après la création du client OAuth |
Les jetons d'accès et d'actualisation sont renvoyés au client. Vous trouverez ci-dessous un exemple de réponse.
{
"access_token" : "3eb33bef34d208479d5ee291307c330864b40e87"
"expires_in":3600,
"type de jeton" : "porteur"
"scope" : "refresh_token read_user_management write_user_management
read_contentprofile_management write_contentprofile_management
read_division_management write_division_management "
"refresh_token" : "7196116f9a1d56411b8fe621d4afda9b9eb4ae93"
}
|
