Utiliser OAuth 2.0

12 minutes

Il y a 1 an

En utilisant l’API de Newforma Konekt ou le BCF REST API, votre application accèdera aux points de terminaison au nom d’un utilisateur de Newforma Konekt. Les utilisateurs devront s’authentifier auprès de Newforma Konekt afin de confirmer leur identité et de donner à votre application la permission d’accéder aux données et d’effectuer des actions en leur nom.

Newforma Konekt utilise le protocole OAuth 2.0 pour permettre aux applications tierces d’accéder aux données. OAuth 2.0 est une norme ouverte de délégation d’accès, couramment utilisée comme un moyen pour les internautes d’accorder à des sites Web ou à des applications l’accès à leurs informations sur d’autres sites web, mais sans leur donner les mots de passe. Ce mécanisme est utilisé par les entreprises pour permettre aux utilisateurs de partager des informations sur leurs comptes avec des applications ou des sites Web tiers.

Devenez un partenaire Newforma Konekt et commencez à utiliser OAuth en remplissant ce formulaire.

Resources utiles

Si vous avez besoin de plus d’informations sur le protocole lui-mê

me, vous pouvez consulter la spécification officielle ici : RFC 6749 – The OAuth 2.0 Authorization Framework. Vous pouvez mettre la main sur le livre OAuth 2.0 Simplified d’Aaron Parecki. Vous pouvez également consulter ces autres ressources How to Use OAuth2, Google Sample OAuth Desktop App Sample and OAuth 2.0 for Mobile & Desktop Apps pour des implémentations plus détaillées.

Rôles OAuth

Les différents rôles OAuth sont :

Entité	Rôle
Application	Il s’agit d’une application web ou de bureau chargée d’effectuer des appels d’API.
Authentication server	Le serveur d’authentification Newforma Konekt est responsable de l’authentification d’un utilisateur (connexion de l’utilisateur).
Authorization server	Le serveur d’autorisation Newforma Konekt est chargé d’autoriser une application à accéder aux API Newforma Konekt et BCF au nom des utilisateurs.
User	Il s’agit d’un utilisateur typique de Newforma Konekt.
Newforma Konekt server	Il expose les points de terminaison de l’API Newforma Konekt et de l’API BCF.
Protected resource	Une ressource retournée ou modifiée par les points de terminaison de l’API.

Définitions

Voici quelques définitions pour vous guider.

Client ID: Il s’agit un identifiant unique public qui identifie l’application interagissant avec le serveur d’autorisation.
Client secret: Il s’agit d’un code privé fourni avec le client ID, qui agit comme un mot de passe. Il doit être stocké de manière sécurisée car il n’est connu que par l’application et le serveur d’autorisation.
Authorization code: Il s’agit d’un code, utilisé une seule fois, pour effectuer une demande de jeton d’accès.
Acces token: Il s’agit d’un code utilisé pour effectuer des requêtes API au nom d’un utilisateur.
Refresh token: Il s’agit d’un code utilisé pour demander un nouveau jeton d’accès lorsque le précédent a expiré.
PKCE: Il s’agit d’un acronyme signifiant Proof Key for Code Exchange (clé de vérification pour l’échange de code). Il offre un moyen plus sûr d’obtenir des jetons d’accès et empêche ainsi les attaquants de les obtenir. Il intègre un vérificateur de code et un challenge dans le processus d’autorisation pour renforcer la sécurité.
Code verifier: Il s’agit d’une chaîne cryptographique aléatoire utilisée par le serveur d’autorisation pour corréler la demande de jeton d’accès avec une demande d’autorisation effectuée précédemment.
Transformation or code challenge method: Il indique l’algorithme appliqué sur le vérificateur de code pour obtenir le code challenge.
Code challenge: Il s’agit d’un challenge dérivé du vérificateur de code (en utilisant une méthode de transformation).

Proof Key for Code Exchange (PKCE)

Il existe deux types de flux de code d’autorisation : standard et PKCE amélioré. Lorsque des applications natives et monopages demandent des jetons d’accès, certains problèmes de sécurité se posent et ils ne sont pas couverts par le seul flux de code d’autorisation standard. Newforma Konekt ne met en œuvre que le flux de code d’autorisation PKCE amélioré.

OAuth 2.0 fournit une version du flux de code d’autorisation qui utilise Proof Key for Code Exchange (PKCE) dont les spécifications peuvent être trouvées ici : OAuth 2.0 RFC 7636.

Processus d’autorisation

Pour débuter, suivez ces instructions.

Vous devez fournir le nom de votre application à l’équipe de Newforma Konekt. Ce nom sera présenté à l’utilisateur sur la page d’authentification.
Pendant le flux de code d’autorisation, le serveur d’autorisation a besoin d’un URI de redirection pour rediriger l’utilisateur lorsque l’authentification est terminée. L’URI est fourni par votre application qui attend une demande du serveur. Il s’agit d’un URI formé comme le suivant http://127.0.0.1:port. Si vous avez besoin de quelque chose de différent pour des besoins ou des contraintes spéciales, vous devez nous fournir l’URI dont vous avez besoin pour ajouter le support dans le serveur d’autorisation.
L’équipe de Newforma Konekt vous fournira alors le client ID et le client secret.
Lorsqu’applicable, il est fortement recommandé de stocker le client secret dans un espace crypté sécurisé. Pour les applications Web, il est recommandé d’utiliser le stockage backend. Pour les applications de bureau, il est recommandé d’utiliser un stockage crypté ou d’utiliser un proxy service sur un backend (si applicable).

Le serveur d’autorisation est situé ici : https://auth.bimtrackapp.co.

Les points de terminaison de l’API Newforma Konekt sont situés ici : https://api.bimtrackapp.co. La documentation est disponible ici : https://bimtrackapis.readme.io/docs.

Les points finaux de l’API BCF sont situés ici : https://bcfrestapi.bimtrackapp.co. La documentation peut être trouvée ici : https://bcfrestapi.bimtrackapp.co/swagger/index.

N.B. : Il n’est pas recommandé d’appeler les API REST Newforma Konekt et BCF dans une application client Javascript (exécutée dans le navigateur). Nous vous suggérons fortement de mettre en œuvre un proxy service sur le backend pour effectuer les appels d’API.

PKCE Enhanced Authorization Code Flow

Voici une description des étapes permettant d’acquérir le jeton d’accès pour effectuer des appels aux API :

Étape 1. L’utilisateur clique sur le bouton Connexion.

Étape 2. L’application envoie la demande d’autorisation au point de terminaison du serveur d’autorisation.

Créer le vérificateur de code

Un vérificateur de code est une chaîne aléatoire cryptographique à haute entropie utilisant les caractères non réservés [A-Z] / [a-z] / [0-9] / « – » / « . ». / « _ » / « ~ », avec une longueur minimale de 43 caractères et une longueur maximale de 128 caractères.

Le vérificateur de code doit avoir une entropie suffisante pour qu’il soit impossible de deviner la valeur.

Créer le code challenge

Deux méthodes de création du code challenge sont supportées.

Méthodes de génération du code challenge

S256

Le code challenge est le hachage SHA256 codé en Base64URL (sans padding) du vérificateur de code.

code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))

Pour obtenir l’autorisation de l’utilisateur, envoyez une demande au serveur d’autorisation à l’adresse suivante : https://auth.bimtrackapp.co//connect/authorize.

Paramètres
client_id	Requis Le client ID pour votre application
redirect_uri	Requis Utilisé par le serveur d’autorisation pour rediriger l’utilisateur lorsque l’authentification est terminée. Votre application attendra une demande du serveur d’autorisation. Si cette valeur ne correspond pas à un URI autorisé, vous obtiendrez une erreur invalid redirect_uri. http://127.0.0.1:port Recherchez l’adresse IP loopback pertinente sur votre plateforme et démarrez un HTTP listener sur un port disponible aléatoire. Remplacez le port par le numéro de port réel sur lequel votre application écoute.
response_type	Requis Définit la valeur du paramètre sur code pour les applications installées.
scope	Requis Une liste de scopes délimitée par des espaces qui identifie les ressources auxquelles votre application peut accéder au nom de l’utilisateur. Les valeurs prises en charge sont les suivantes : BIMTrack_Api : pour accéder aux points de terminaison de l’API Newforma Konekt. BcfWebApi : pour accéder aux points de terminaison de l’API BCF. offline_access : pour demander un jeton de rafraîchissement. openid : ce champ est obligatoire. Il indique que l’application a l’intention d’utiliser OIDC pour vérifier l’identité de l’utilisateur.
code_challenge	Recommandé La valeur code_challenge calculée ci-dessus.
code_challenge_method	Recommandé La seule valeur prise en charge pour ce paramètre est S256
state	Recommandé Spécifie toute valeur de chaîne que votre application utilise pour maintenir l’état entre votre demande d’autorisation et la réponse du serveur d’autorisation. Le serveur renvoie la valeur exacte que vous envoyez sous forme de paire nom=valeur. Vous pouvez valider la réponse pour vous assurer que la demande et la réponse proviennent du même navigateur, ce qui vous protège contre les attaques telles que la falsification des demandes intersites.

Exemple d’URL de demande d’autorisation

https://auth.bimtrackapp.co/connect/authorize?

response_type=code&

scope=BIMTrack_Api%20openid&

redirect_uri=http%3A%2F%2F127.0.0.1%3A18215&

client_id=your_client_id&

state=-XGJum969rPJU3NUmzwYUuyrGR7S098u_SQMuxcu1WY&

code_challenge=v0jvOB_WGqP349D-ahfv7V5-ANvZfV7gMai1x-Obsj0&

code_challenge_method=S256

Étape 3. L’utilisateur est redirigé vers la page du serveur d’authentification pour entrer ses informations d’identification.

Étape 4. L’utilisateur saisit ses informations d’identification, clique sur le bouton Connexion et donne son consentement à l’application.

Étape 5. Une fois autorisé, le serveur d’autorisation redirige l’utilisateur vers le redirect_uri et renvoie un code d’autorisation à l’application.

Étape 6. L’application envoie la demande de jeton d’accès.

Pour échanger un code d’autorisation contre un jeton d’accès, appelez le point de terminaison https://auth.bimtrackapp.co/connect/token et définissez les paramètres suivants :

Champs
client_id	Requis Le client ID pour votre application.
client_secret	Requis Le client secret calculé précédemment.
code	Requis Le code d’autorisation reçu à l’étape 5.
code_verifier	Requis La valeur du vérificateur de code créée précédemment.
grant_type	Requis La valeur de authorization_code.
redirect_uri	Requis Le même URI de redirection que dans l’étape 2.

Exemple d’URL de demande de jeton d’accès

POST /connect/token HTTP/1.1

Host: https://auth.bimtrackapp.co

Content-Type: application/x-www-form-urlencoded

code=4f46b8cc568bf2426263e6ebcc5300b3ba5da7e84ac829c826635bdce8bd2196&

client_id=your_client_id&

client_secret=your_client_secret&

redirect_uri=http%3A%2F%2F127.0.0.1%3A18215&

grant_type=authorization_code

Étape 7. Le serveur d’autorisation répond en envoyant les jetons d’accès. Si la portée offline_access a été fournie précédemment, la réponse contiendra également un jeton de rafraîchissement. Ce jeton est utilisé par votre application pour rafraîchir votre jeton d’accès lorsqu’il expire. Les jetons d’accès ont une durée de vie de 2 heures. Si applicable, il est fortement recommandé de stocker le ou les jetons d’accès et de rafraîchissement dans un espace de stockage crypté sécurisé. Pour les applications Web, il est recommandé d’utiliser le stockage backend. Pour les applications de bureau, nous recommandons d’utiliser un stockage crypté (lorsqu’il n’y a pas de backend disponible).

Étape 8. L’application peut maintenant faire des appels aux points de terminaison de l’API en utilisant le jeton d’accès.

Exemple d’URL de demande d’API

GET /v3/hubs HTTP/1.1

Host: https://api.bimtrackapp.co

Authorization: bearer access_token

Étape 9. Le serveur Newforma Konekt répond en renvoyant la ressource protégée demandée.

Le stockage sécurisé des jetons d’accès et de rafraîchissement permet la réutilisation ultérieure de la même session. Cela améliore l’expérience de l’utilisateur en supprimant le besoin de se ré-authentifier à chaque fois que l’application est redémarrée.

N.B. : Tous les détails concernant le contenu des demandes et des réponses se trouvent dans les liens OAuth 2.0 fournis en haut de cette section.

Les bibliothèques suivantes peuvent être utilisées pour de nombreuses interactions avec les points de terminaison définis OpenID Connect et OAuth :