Authentification (REST)

L'architecture REST de Broadsign prend en charge deux méthodes d'authentification : un jeton HTTP et une empreinte digitale de certification/clé publique.

Nous vous recommandons d’utiliser ces méthodes de la manière suivante :

  • Jeton HTTP : Le jeton HTTP est facile à générer et à utiliser. Nous vous recommandons d’utiliser un jeton HTTP pour authentifier les appels API vers le domaine de test. Voir À propos de l'environnement de test (REST).
  • Certification/Empreinte digitale de clé publique : En raison de son niveau de sécurité élevé, nous vous recommandons d'utiliser la certification pour authentifier les appels effectués vers votre domaine de production.

Note : L’utilisation de chaque méthode d’authentification nécessite un certain travail dans Broadsign Control Administrator. Vous aurez besoin d'un utilisateur enregistré sur un domaine actif.

Note : Vos domaines de test et de production sont des entités distinctes. Vous aurez besoin d'un utilisateur Broadsign Control API pour chaque domaine, chacun avec son propre identifiant unique. De plus, vous devrez authentifier les appels sur chaque domaine séparément (c'est-à-dire des jetons distincts ou des empreintes de clé publique sur chacun).

Vous pouvez générer et utiliser un jeton HTTP pour un accès sécurisé à l'architecture REST de Broadsign. Un utilisateur disposant des privilèges nécessaires génère le jeton dans Broadsign Control Administrator. Cet utilisateur transmet ensuite les informations d’identification dans les en-têtes de ses requêtes REST.

Vous devez appeler REST via HTTPS. Les appels effectués via HTTP ou sans authentification échoueront.

Pour demander qu'un utilisateur bénéficie d'un accès REST, contactez Broadsign Services et fournissez l'identifiant de l'utilisateur.

Note : Lorsque vous générez le jeton HTTP, vous devez le copier dans votre presse-papiers. Une fois la boîte de dialogue fermée, vous ne pourrez plus voir le jeton. Pour le voir, vous devez en générer un nouveau. Une fois copié dans votre presse-papiers, nous vous recommandons de le coller immédiatement dans un éditeur de texte.

Pour générer le jeton HTTP :

  1. Sélectionnez l’utilisateur de votre domaine qui utilisera l’API REST.
  2. Pour activer l'accès, contactez Broadsign Services. Fournissez-leur l'identifiant de votre domaine et de l'utilisateur de l'API.

    3. Broadsign Services confirmera l'accès à l'API pour cet identifiant d'utilisateur.

  3. Dans Broadsign Control Administrator, ouvrez la fenêtre User Properties (voir Modifier les propriétés de l'utilisateur). Accédez à l’onglet Credentials.

  4. Pour obtenir un jeton, sous REST API Authorization Token, cliquez sur Generate Token. La boîte de dialogue « REST API Token » s'ouvre.

    Note : Lorsque vous générez le jeton HTTP, vous devez le copier dans votre presse-papiers. Une fois la boîte de dialogue fermée, vous ne pourrez plus voir le jeton. Pour le voir, vous devez en générer un nouveau. Une fois copié dans votre presse-papiers, nous vous recommandons de le coller immédiatement dans un éditeur de texte.

  5. Cliquez sur OK, puis sur Apply.

Voici un exemple de requête avec le jeton HTTP :

Copier 
curl  -X GET "https://api-sandbox.broadsign.com:10889/rest/criteria/v8/12345" -H "accept: application/json" -H "Authorization: Bearer YourAPIKeyHere"

Note : Cet exemple inclut le point de terminaison d’un domaine d'environnement de test. Le point de terminaison de production est différent : https://api.broadsign.com

Lors de l'intégration avec Broadsign Control API en production, nous recommandons un certificat et une clé cryptographiques.

Vous devez les installer sur la machine cliente associée à un utilisateur — disposant des privilèges appropriés — dans Broadsign Control Administrator. Pour des raisons d'audit et de sécurité, il est préférable de créer un nouvel utilisateur dédié exclusivement à cette utilisation Broadsign Control API. Ajoutez simplement un nouvel utilisateur via Broadsign Control Administrator, choisissez un mot de passe arbitraire et attribuez les privilèges appropriés.

Ensuite, vous devez générer une clé privée et soumettre une demande de signature de certificat (CSR) à Broadsign. Broadsign répondra avec un certificat signé et une empreinte de clé publique :

  • Le certificat signé et votre clé privée sont vos jetons d’authentification.
  • L'empreinte de la clé publique est attribuée à l'utilisateur que vous avez créé, permettant ainsi à Broadsign Server d'authentifier l'utilisateur et lui attribuer le contexte de sécurité approprié.

Pour authentifier votre utilisateur Broadsign Control API :

  1. Créer la clé privée :

    Copier 
    openssl genrsa -out sdk_key.pem 2048

  2. Créez la demande de signature de certificat (CSR) Broadsign :

    Copier 
    openssl req -new -key sdk_key.pem -out sdk_req.pem
    • Remplissez les champs avec précision.
    • NE spécifiez AUCUN des attributs supplémentaires suivants :
      • un mot de passe de défi
      • un nom de société facultatif

  3. Envoyez la demande de signature de certificat (CSR) à Broadsign. Inclure les informations suivantes :

    • À : services@broadsign.com
    • Objet : SDK CSR
    • Pièce jointe: [sdk_req.pem]

    • Corps du message : Veuillez trouver ci-joint la demande de signature de certificat API pour [nom de votre entreprise].

      Avertissement : N'envoyez pas votre clé privée. Conservez-la en lieu sûr en permanence. Toute personne ayant accès à votre clé privée pourrait apporter des modifications non autorisées à votre domaine.

      Note : Si l'adresse e-mail à partir de laquelle vous envoyez la demande n'est pas enregistrée auprès de la communauté Broadsign, vous recevrez un e-mail de retour. Vous devrez désigner un contact enregistré au sein de votre organisation pour nous contacter afin d'enregistrer l'adresse électronique.

  4. Recevez le certificat signé et l'empreinte de la clé publique de Broadsign.
  5. Attribuez l'empreinte de clé publique à votre utilisateur Broadsign Control API désigné :
    1. Dans Broadsign Control Administrator, dans les onglets de ressources sur la gauche, sélectionnez Users.
    2. Trouvez et double-cliquez sur votre utilisateur Broadsign Control API.
    3. Dans la fenêtre User Properties, allez à l'onglet Credentials.

    4. Dans la section Public Key Fingerprint, collez votre empreinte digitale.

      • L'utilisateur effectuant les requêtes doit posséder une empreinte digitale valide correspondant au certificat utilisé côté client de la connexion SSL à authentification mutuelle.
      • L'empreinte digitale est une série de caractères hexadécimaux, 20 paires séparées par des deux-points.

Le certificat local permet à Broadsign Server de vous authentifier.

Lors de l'envoi de requêtes à Broadsign Control API, la requête nécessite un fichier de clé et de certificat fusionnés. Concaténez votre clé privée et le certificat signé fourni par Broadsign Services.

Pour créer votre certificat local :

  1. Placez les fichiers sdk_key.pem et sdk_cert.pem dans le même dossier.
  2. À l’aide du terminal, accédez au répertoire.

  3. Exécutez la commande ci-dessous :

    Copier 
    cat sdk_key.pem sdk_cert.pem > merged_cert.pem

Pour les utilisateurs Windows :

  1. À l’aide de votre éditeur de texte, créez un nouveau fichier nommé merged_cert.pem.
  2. Ajoutez le contenu de sdk_key.pem et sdk_cert.pem, dans cet ordre.

Le fichier final devrait ressembler à l'image ci-dessous.

Note : Il s'agit d'un faux certificat. Ne le copiez pas.

Ne confondez pas la portée telle que nous utilisons le terme dans Broadsign Control Administrator, avec une portée telle que nous utilisons le terme dans Broadsign Control API.

  • Dans Broadsign Control Administrator , « scoping » fait référence à la restriction de ce que les utilisateurs peuvent voir, comme décrit dans la fonctionnalité Portée.
  • Dans Broadsign Control API « scoping » fait référence à la réduction des résultats d'opérations de liste spécifiques.

    • Note : Il n'est pas possible de limiter les ressources accessibles à un utilisateur d'API sur un point de terminaison spécifique si l'utilisateur dispose des privilèges d'accès nécessaires pour cela.