Développement d'un service web d'agent externe

Développement d'un service web d'agent externe

Cet article vous guidera dans le développement d'un service web d'agent externe avec express.js en utilisant un exemple d'application comme modèle.

Architecture de haut niveau

Vous développerez le service web de l'agent externe**(service web extauthn ). Sa fonction est de :

• Recevoir des demandes de l' agent de pont
• Effectuer des opérations sur la base de données source d'identité de votre organisation via son propre protocole spécifique à la base de données
• Répondre à l' agent-relais conformément aux contrats de l'API

En savoir plus sur l'architecture IBM Security Verify Bridge.

Les contrats API

Demande de contrat

Le service web de l'agent externe reçoit des demandes de l' agent pont. Voici les détails du contrat de demande :

EXEMPLE DE DEMANDE HTTP

POST  https://external.mod.com/action/
content-type: application/json
accept: application/json
authorization: Basic gobledeegoop

{
    "operation": "password-verify",
    "parameters": {
      "username": "scott",
      "password": "scott11111"
    },
    "requestedAttributes": ["cn", "mobile_number", "display_name"]
}

Contrat de réponse

Les codes d'état sont les suivants :

EXEMPLE DE RÉPONSE HTTP

HTTP/1.1 200 OK
content-type: application/json

{
    "operation": "password-verify",
    "status": {
        "result": "SUCCESS"
    },
    "parameters": {
        "groups": [
            {
                "name": "developer",
                "id": "608000GTNH"
            },
            {
                "name": "admin",
                "id": "608000GTNF"
            }
        ],
        "user": {
            "cn": [
                "Scott Admin"
            ],
            "mobile_number": [
                "111-222-3333"
            ],
            "displayName": [
                "Scott"
            ]
        }
    }
}

Certaines opérations peuvent ne pas générer de corps de réponse HTTP RESPONSE BODY) et, dans ce cas, un 204 est acceptable au lieu d'un 200 (avec longueur de contenu : 0).

opération "get-status

Voici des exemples de demande/réponse pour l'opération get-status

Demande

{
    "addressedTo": "extauthn",
    "id": "0",
    "operation": "get-status"
}

Réponse

{
    "replyFrom": "extauthn",
    "status": {
        "result": "SUCCESS"
    },
    "id": "0",
    "operation": "get-status",
    "connection": "OK"
}

Jetez un coup d'œil à l'exemple d'application fourni pour voir comment les contrats API peuvent être mis en œuvre.

Authentification

Avant de traiter les demandes ci-dessus, votre service web doit confirmer l'identité de l' agent-relais afin de protéger votre service web contre toute utilisation non autorisée. L' agent bridge s'identifiera auprès de votre service web via l'un des flux d'authentification suivants :

L' exemple d'application fourni démontre une mise en œuvre fonctionnelle de chacun de ces flux d'authentification. Par défaut, l'exemple d'application utilise l' authentification de base. Voir la section sur l'activation des flux d'authentification dans l'exemple d'application pour utiliser les autres flux.

Utilisation de l'exemple d'application fourni

Un exemple d'implémentation de référence d'un service web d'agent externe est fourni via le dépôt GitHub. L' exemple d'application montre comment :

1. Mettre en œuvre les contrats de l'API
2. S'authentifier avec l'exemple d'application

Note : Bien que l'exemple d'application soit conçu pour traiter les demandes de l'agent bridge, il n'est pas nécessaire d' exécuter l'agent bridge lors du développement/test de l'exemple d'application. Au lieu de cela, vous pouvez utiliser les scripts CURL fournis pour simuler les demandes de l'agent-relais. Voir l'utilisation de l'exemple d'application comme source d'identité ISV lorsque vous êtes prêt à tester une instance ISV en direct.

Télécharger et exécuter l'exemple d'application

Pour télécharger et exécuter l'exemple d'application, clonez le dépôt :

git clone [email protected]:IBM-Security/Verify-Bridge-Authentication-Sample-App.git

Cela créera un répertoire appelé Verify-Bridge-Authentication-Sample-App/. Le répertoire contient deux sous-répertoires :

1. sample-application/- hébergement de l'exemple d'application
2. tests/- hébergement des tests CURL

Changez de répertoire pour accéder au répertoire sample-application/ et exécutez npm install pour installer les paquets nécessaires.

cd Verify-Bridge-Authentication-Sample-App/sample-application
npm install

Avant de lancer votre serveur, vous devez définir les variables d'environnement et générer les certificats TLS requis, comme indiqué dans les sections suivantes.

Configuration du service web (variables d'environnement)

La racine du répertoire sample-application contient un fichier appelé .env_example. Renommez-le en .env

# Web Server variables
PORT=8555
LOGGER_PREFIX='Extauthn Web Service'

# Authorization specific variables...

Vous pouvez laisser les variables spécifiques à l'authentification sur leurs valeurs par défaut pour l'instant. Pour en savoir plus, voir la section sur l'authentification.

Générer les certificats TLS

L' agent bridge communiquera avec le service web de l'agent externe via https. Vous devrez générer les certificats suivants et leurs clés privées :

Avant de générer les certificats pour l'application d'exemple, renommez le fichier certs/.env_example en .env. Ouvrez le fichier, vous devriez voir quelque chose comme ce qui suit :

# TLS generation variables
BRIDGE_AGENT_IP=
BRIDGE_AGENT_DNS=

WEB_SERVER_IP=
WEB_SERVER_DNS=

COUNTRY='AU'
STATE='Queensland'
LOCATION='Gold Coast'
ORGANIZATION='My Company'

Par défaut, l'exécution du script certs.sh génère des certificats qui ne fonctionnent que sur la machine locale ( 127.0.0.1 ). Cela convient si vous avez l'intention d'exécuter l' agent bridge et le service web sur la machine locale. Toutefois, si vous prévoyez d'exécuter l' agent bridge (ou les tests CURL qui le simulent) et le service web sur des machines différentes, vous devez définir les valeurs de BRIDGE_AGENT_IP et WEB_SERVER_IP comme étant les adresses IP de ces machines. Ou si vous connaissez leurs noms d'hôte, définissez-les en conséquence.

BRIDGE_AGENT_IP='172.16.236.128'
BRIDGE_AGENT_DNS=bridge_agent.myhost

WEB_SERVER_IP='172.16.236.1'
WEB_SERVER_DNS=extauthn_webserver.myhost

Générez les certificats TLS requis en exécutant le script cert.sh dans le répertoire certs/.

Exécuter

chmod +x certs.sh
./certs.sh

Votre répertoire certs/ devrait maintenant contenir les fichiers suivants :

drwxr-xr-x user group 768 B  Thu Oct 13 21:50:57 2022 .
drwxr-xr-x user group 416 B  Thu Oct 13 18:56:08 2022 ..
.rw-r--r-- user group 223 B  Thu Oct 13 21:41:51 2022 .env
.rw-r--r-- user group  41 B  Thu Oct 13 21:28:15 2022 .gitignore
.rw-r--r-- user group 180 B  Thu Oct 13 21:50:57 2022 cert.extauthn.agent.conf
.rw-r--r-- user group 261 B  Thu Oct 13 21:50:57 2022 cert.extauthn.client.conf
.rwxr-xr-x user group 3.8 KB Thu Oct 13 21:41:00 2022 certs.sh
.rwxr-xr-x user group 130 B  Thu Oct 13 19:33:59 2022 cleanup.sh
.rw-r--r-- user group 307 B  Thu Oct 13 21:50:56 2022 csr.extauthn.agent.conf
.rw-r--r-- user group 310 B  Thu Oct 13 21:50:57 2022 csr.extauthn.client.conf
.rw-r--r-- user group 1.3 KB Thu Oct 13 21:50:57 2022 extauthn.agent.crt
.rw-r--r-- user group 1.0 KB Thu Oct 13 21:50:56 2022 extauthn.agent.csr
.rw-r--r-- user group 1.6 KB Thu Oct 13 21:50:56 2022 extauthn.agent.key
.rw-r--r-- user group 2.5 KB Thu Oct 13 21:50:57 2022 extauthn.agent.p12
.rw-r--r-- user group 1.1 KB Thu Oct 13 21:50:56 2022 extauthn.caroot.crt
.rw-r--r-- user group 1.7 KB Thu Oct 13 21:50:56 2022 extauthn.caroot.key
.rw-r--r-- user group 1.3 KB Thu Oct 13 21:50:57 2022 extauthn.client.crt
.rw-r--r-- user group 1.0 KB Thu Oct 13 21:50:57 2022 extauthn.client.csr
.rw-r--r-- user group 1.6 KB Thu Oct 13 21:50:57 2022 extauthn.client.key
.rw-r--r-- user group 2.5 KB Thu Oct 13 21:50:57 2022 extauthn.client.p12
.rw-r--r-- user group  17 B  Thu Oct 13 21:50:57 2022 extauthn.srl
.rw-r--r-- user group 130 B  Thu Oct 13 21:50:56 2022 ssl.cfg

NOTE IMPORTANTE

Les certificats générés sont destinés à tester l'exemple de service web et ne doivent pas être utilisés dans votre environnement de production. Lorsque vous êtes prêt à déployer, assurez-vous d'utiliser les propres certificats de votre organisation ou de les faire générer pour les utiliser avec le service web de l'agent externe en conséquence.

Exécution de l'exemple d'application

Assurez-vous que vous avez configuré le service web et créé les certificats TLS, puis lancez le serveur en tapant

npm start

Si vous voyez la sortie suivante, votre serveur fonctionne correctement.

HTTPS Listening on port          8555

L'application fonctionne avec nodemon, ce qui signifie que toute modification apportée à l'application redémarre automatiquement le serveur.

Vous pouvez tester l'application à l'aide des tests CURL fournis pour vous assurer que l'application est conforme aux contrats de l'API.

Si vous souhaitez utiliser l' exemple d'application comme source d'identité pour votre locataire ISV et le voir fonctionner en temps réel, vous devrez.. :

1. Mise en place de l'agent d'identité sur l'ISV
2. Installer et exécuter l' agent bridge

Tester votre service web avec des requêtes CURL

Une fois que votre service web est en cours d'exécution, vous pouvez tester qu'il est conforme aux contrats de l'API en utilisant la commande CURL pour accéder manuellement au point de terminaison /action. Pour vous aider, nous avons fourni divers scripts permettant de tester chacune des opérations.

Ouvrez le répertoire tests/curl/, vous devriez voir les sous-répertoires suivants, chacun correspondant à une méthode d'authentification différente :

1. BasicAuth/
2. BasicAuthOverMTLS/
3. MTLS/

Dans ces répertoires se trouvent les scripts bash suivants :

Avant d'exécuter ces scripts, ouvrez le fichier tests/.env_example et renommez-le en .env. Veillez à définir l'hôte et le port de votre service web ainsi que les détails du certificat. Par défaut, ces détails fonctionneront avec l' exemple d'application, modifiez-les si nécessaire.

# Path to certificates directory
CERT_PATH='../../../sample-application/certs/'
CA_CERT_NAME='extauthn.caroot.crt'

# Extauthn server info
EXTAUTHN_SERVER_HOST=localhost
EXTAUTHN_SERVER_PORT=8555

# Basic Auth info
BASIC_AUTH_USERNAME=admin
BASIC_AUTH_PASSWORD=passw0rd
INVALID_BASIC_AUTH_USERNAME=jerry
INVALID_BASIC_AUTH_PASSWORD=abcdef

# Client Cert and Key for mtls
CLIENT_CERT_NAME='extauthn.client.crt'
CLIENT_CERT_KEY='extauthn.client.key'

EXTAUTHN_SERVER_HOST et EXTAUTHN_SERVER_PORT font référence au nom d'hôte et au port où votre service web est exécuté.

L'adresse CERT_PATH indique simplement l'emplacement du répertoire certs/ par rapport aux emplacements des scripts de test.

Exécution des scripts CURL

Avant d'exécuter les tests, assurez-vous que l'intergiciel d'authentification approprié est activé. L'intergiciel par défaut étant l'authentification de base, vous devez exécuter les tests dans le répertoire tests/curl/BasicAuth/.

Pour exécuter l'un des tests bash, il suffit de lancer le script correspondant, par exemple password-verify :

chmod +x password-verify.sh
./password-verify.sh

Vous obtiendrez un résultat qui ressemble à ce qui suit

HTTP/1.1 200 OK
X-Powered-By: Express
Content-Type: application/json; charset=utf-8
Content-Length: 248
ETag: W/"f8-bDOG/ZHdodpQnYcCaI1Xhpf/Wgc"
Date: Mon, 10 Oct 2022 12:32:21 GMT
Connection: keep-alive
Keep-Alive: timeout=5

{"operation":"password-verify","status":{"result":"SUCCESS"},"parameters":{"groups":[{"name":"developer","id":"608000GTNH"},{"name":"admin","id":"608000GTNF"}],"user":{"cn":["Scott Admin"],"mobile_number":["111-222-3333"],"displayName":["Scott"]}}}%            

Au fur et à mesure que vous développez votre application, modifiez le contenu du script bash pour obtenir les résultats souhaités. Par exemple, pour voir le résultat d'une requête pour un utilisateur qui n'est pas dans la source de données, modifiez la requête password-verify.sh pour demander un utilisateur qui n'existe pas, dans cet exemple nous demandons frankie

--data-raw '{
    "operation": "password-verify",
    "parameters": {
      "username": "frankie",
      "password": "scott11111"
    },
    "requestedAttributes": ["cn", "mobile_number", "displayName"]
}'

Vous obtiendrez la réponse suivante

HTTP/1.1 200 OK
X-Powered-By: Express
Content-Type: application/json; charset=utf-8
Content-Length: 110
ETag: W/"6e-AX+whB1hU5sA52YZ3uvRBOccdL4"
Date: Mon, 10 Oct 2022 12:34:57 GMT
Connection: keep-alive
Keep-Alive: timeout=5

{"operation":"password-verify","status":{"result":"USER_NOT_FOUND","message":"User not found in data source"}}%               

Démontrer une gestion correcte de USER_NOT_FOUND comme spécifié dans les contrats d'API.

Utilisation de l'exemple d'application avec l'ISV

Si vous souhaitez utiliser l'exemple d'application comme source d'identité pour votre locataire ISV, vous devez procéder comme suit :

1. Créez votre agent d'identité sur ISV
2. Installer et exécuter l'agent bridge

1. Création d'un agent d'identité sur ISV

Pour utiliser l'exemple d'application fourni comme source d'identité sur l'ISV, vous devez créer une source d'identité sur l'ISV. Par défaut, l' exemple d'application utilise l'authentification de base. Pour les autres types d'authentification, voir la section sur l 'authentification.

L' exemple d'application utilisant l'authentification de base nécessitera les paramètres suivants :

Attributs

Pour les attributs, entrez displayName, givenName, mobile_number. Il s'agit de la liste des attributs que nous souhaitons que l' agent bridge demande au service web et qui est renvoyée en cas de succès de la requête password-verify. Ces attributs et valeurs sont ensuite mis à disposition pour la mise en correspondance avec les attributs des comptes de l'annuaire en nuage de l'ISV au cours de l'approvisionnement juste à temps (Just-In-Time Provisioning - JITP). Consultez le fichier de l'exemple de source de données sample-application/data_source/data_source.js pour voir quels attributs peuvent être demandés à l' exemple d'application.

Lors du développement d'un service web d'agent externe, l'administrateur de l'ISV qui effectue cette étape de configuration de l'agent d'identité devra consulter le développeur du service web pour savoir à quels attributs le service web a accès et peut renvoyer une demande password-verify qui a abouti.

Définir les correspondances d'attributs

mobile_number->mobile_number
givenName->given_name

Nommez votre agent et votre source d'identité et appuyez sur Save and continue pour créer l'agent d'identité de votre exemple d'application.

Enfin, vous recevrez le site API credentials que votre agent-relais vous demandera. Téléchargez l' agent Bridge depuis X-Force App Exchange et utilisez les informations d'identification fournies au cours de cette étape lors de l'installation et de l'exécution de l'agent Bridge.

2. Installation et exécution de l'agent Bridge sous Windows

Téléchargez l' agent Bridge depuis X-Force App Exchange et exécutez le programme d'installation en suivant les instructions.

Après l'installation, vous verrez apparaître le site Tenant Configuration screen illustré ci-dessous

Saisissez les adresses Client ID et Client Secret que vous avez reçues lors de la création de l'agent d'identité.

Cochez la case enable tracing et prenez note de Trace file name (par défaut bridge_agent.log ).

L' agent de pont doit maintenant fonctionner en tant que service. Si vous souhaitez voir la sortie de la console de l' agent bridge, ouvrez powershell et tapez la commande suivante, en remplaçant le chemin d'accès au fichier journal que vous avez créé lors de la configuration de l'agent bridge par le chemin d'accès au fichier journal :

Get-Content 'C:\Program Files\IBM\BridgeAgent\bridge_agent.log' -Tail 50 -Wait

Le journal de l'agent de liaison peut vous aider à résoudre les problèmes que vous rencontrez.

Redémarrage ou remise en service de l'agent Bridge

Il se peut que vous deviez arrêter ou redémarrer le service de l'agent de pont. Pour ce faire, sur votre ordinateur Windows, appuyez sur Win+R et tapez services.msc

Dans l'écran suivant, sélectionnez le service nommé IBM Security Verify Bridge (ibm_bridge_agent) et cliquez sur stop ou restart pour arrêter ou redémarrer l'agent bridge.

L'authentification a abouti

Une fois lancé, l' agent pont se connectera à l'ISV et récupérera la configuration que vous avez créée lors de la configuration de l'agent d'identité. L'agent-relais tentera alors de se connecter à l'un des URI spécifiés pour votre service web dans la configuration de l'agent d'identité.

Vous devriez voir l' application exemple enregistrer dans sa console quelque chose comme ce qui suit :

Extauthn Web Service | HTTPS Listening on port   8555
Extauthn Web Service |
Request headers received:
Extauthn Web Service | {"host":"172.16.236.1:8555","user-agent":"Go-http-client/1.1","transfer-encoding":"chunked","accept":"application/json","authorization":"Basic YWRtaW46cGFzc3cwcmQ=","content-type":"application/json","accept-encoding":"gzip"}
Extauthn Web Service | Attempting Basic Authentication
Extauthn Web Service | Basic Auth: {"name":"admin","pass":"passw0rd"}
Extauthn Web Service | Basic auth successful
Extauthn Web Service | Request body:
Extauthn Web Service | {"addressedTo":"extauthn","id":"0","operation":"get-status"}
Extauthn Web Service | Replied:
Extauthn Web Service | {"replyFrom":"extauthn","status":{"result":"SUCCESS"},"id":"0","operation":"get-status","connection":"OK"}

Félicitations, l'agent bridge s'authentifie avec succès auprès de votre service web en utilisant l'authentification de base sur TLS. Vous pouvez maintenant vous connecter à votre locataire ISV à l'aide des informations d'identification figurant dans le fichier data_source/data_source.json.

Connexion à l'ISV en utilisant l'exemple d'application comme source d'identité

L' agent de liaison s'étant authentifié avec succès auprès du service web, vous devriez maintenant pouvoir vous connecter à l'ISV en utilisant les informations d'identification spécifiées dans la source de données fictive ( data_source/data_source.json ).

Sélectionnez la source d'identité que vous avez créée :

Saisissez les informations d'identification figurant dans le fichier data_source/data_source.json :

username: scott
password: scott11111

Votre exemple d'application devrait afficher les informations suivantes sur la console

Request headers received:
Extauthn Web Service | {"host":"172.16.236.1:8555","user-agent":"Go-http-client/1.1","transfer-encoding":"chunked","accept":"application/json","authorization":"Basic YWRtaW46cGFzc3cwcmQ=","content-type":"application/json","accept-encoding":"gzip"}
Extauthn Web Service | Attempting Basic Authentication
Extauthn Web Service | Basic Auth: {"name":"admin","pass":"passw0rd"}
Extauthn Web Service | Basic auth successful
Extauthn Web Service | Request body:
Extauthn Web Service | {"enqueuedTime":"2022-10-14 01:52:08.192","operation":"password-verify","parameters":{"password":"scott11111","username":"scott"},"requestedAttributes":["displayName","givenName","SN"]}
Extauthn Web Service | Replied
Extauthn Web Service | {"operation":"password-verify","status":{"result":"SUCCESS"},"parameters":{"groups":[{"name":"developer","id":"608000GTNH"},{"name":"admin","id":"608000GTNF"}],"user":{"displayName":["Scott"],"givenName":["Scott"],"SN":["Admin"]}}}

Vous devriez maintenant être connecté à l'ISV sous le nom de scott.

Activation des flux d'authentification dans l'application modèle

L' exemple d'application prend en charge les méthodes d'authentification suivantes :

1. Auth de base (par défaut)
2. MTLS
3. JWT signé symétriquement
4. JWT signé asymétriquement
5. OAuth

MTLS peut également être utilisé en conjonction avec Basic Auth et OAuth, voir l'activation de MTLS avec ces flux.

Authentification de base

L'authentification de base attend qu'un en-tête d'autorisation soit envoyé au service web au format Basic username:password où username:password est codé en base64. Par exemple, un en-tête de requête pour les informations d'identification username:password de admin:passw0rd ressemblerait à ce qui suit :

"authorization":"Basic YWRtaW46cGFzc3cwcmQ="

Activation de l'authentification de base dans l'application modèle

Pour activer l'authentification de base dans votre exemple d'application, ouvrez server.js et assurez-vous que l'intergiciel basicAuthen est décomplété

// Authentication (uncomment desired)
app.use(basicAuthen);                       // Basic Auth
// app.use(mtls);                              // MTLS
// app.use(symmetricJwt);                      // Symmetric signed JWT
// app.use(asymmetricJwt);                     // Asymmetric signed JWT

Définition des variables .env pour l'authentification de base

Ouvrez .env à la racine du répertoire de votre projet et définissez le nom d'utilisateur et le mot de passe attendus. Il s'agit du nom d'utilisateur et du mot de passe que votre serveur s'attend à voir dans l'en-tête d'autorisation. Vous pouvez laisser ces valeurs telles quelles.

# Basic Auth Variables
BASIC_AUTH_USERNAME=admin
BASIC_AUTH_PASSWORD=passw0rd

CONFIGURATION DE L'AGENT D'IDENTITÉ POUR L'AUTHENTIFICATION DE BASE

Dans l'interface utilisateur de l'agent d'identité, configurez l'authentification de base

Authentification MTLS

Lors de l'utilisation de MTLS, l' agent passerelle présente son certificat client au service web. Le service web vérifie si le certificat est fiable (signé par une autorité de certification fiable). Si le certificat du client présenté est fiable, le service web autorisera la demande, sinon elle sera refusée.

Activation de MTLS dans l'application d'exemple

Pour activer l' authentification MTLS dans votre exemple d'application, ouvrez server.js et assurez-vous que l'intergiciel mtls est décomplété

// Authentication (uncomment desired)
// app.use(basicAuthen);                       // Basic Auth
app.use(mtls);                              // MTLS
// app.use(symmetricJwt);                      // Symmetric signed JWT
// app.use(asymmetricJwt);                     // Asymmetric signed JWT

Pour utiliser MTLS, assurez-vous que la configuration de votre serveur https comprend les éléments suivants

requestCert: true,
rejectUnauthorized: false,

Par exemple

const httpsServerConfig = {
    key: fs.readFileSync(PATH_TO_KEY),
    cert: fs.readFileSync(PATH_TO_CRT),
    ca: fs.readFileSync(PATH_TO_CA),
    requestCert: true,
    rejectUnauthorized: false,
}

CONFIGURATION DE L'AGENT D'IDENTITÉ POUR LES MTLS

Avant de configurer MTLS, veillez à importer le site client certificate et la clé privée associée sur la machine Windows.

Importation du certificat racine avec Powershell

Démarrez powershell en tant qu'administrateur puis tapez la commande suivante en remplaçant C:\extauthn.caroot.crt par le chemin de votre extauthn.caroot.crt que vous avez créé lors de la configuration de votre certificat TLS.

Import-Certificate -FilePath C:\extauthn.caroot.crt -CertStoreLocation Cert:\LocalMachine\root

Importation du certificat et de la clé du client avec Powershell

Démarrez powershell en tant qu'administrateur puis tapez la commande suivante en remplaçant C:\extauthn.client.p12 par le chemin de votre extauthn.client.p12 que vous avez créé lors de la configuration de votre certificat TLS.

Import-PfxCertificate -FilePath C:\extauthn.client.p12 -CertStoreLocation Cert:\LocalMachine\My

Vous devriez obtenir un résultat semblable à celui qui suit

   PSParentPath: Microsoft.PowerShell.Security\Certificate::LocalMachine\My

Thumbprint                                Subject
----------                                -------
8BEB4C0A77090F2BEDA49BCC0A57B03E8242540B  CN=extauthn.client, OU=MyUnit, O=MyOorg, S=QLD, C=AU

Copiez la valeur sous le sujet CN=extauthn.client, OU=MyUnit, O=MyOorg, S=QLD, C=AU, vous aurez besoin de cette valeur lors de la configuration de votre Agent d'Identité sur ISV.

PARAMÈTRES DE L'AGENT D'IDENTITÉ POUR LES MTLS

Dans l'interface utilisateur de l'agent d'identité, définissez le type d'authentification sur MTLS, puis définissez les valeurs suivantes :

Exemple de la Private Key Certificate Name

Utilisation de MTLS avec Basic Auth ou OAuth

Si vous souhaitez utiliser MTLS en plus de Basic Auth ou OAuth, ouvrez le fichier server.js et décommentez MTLS ET l'autre type d'authentification que vous souhaitez utiliser

// Authentication (uncomment desired)
app.use(basicAuthen);                       // Basic Auth
app.use(mtls);                              // MTLS
// app.use(symmetricJwt);                      // Symmetric signed JWT
// app.use(asymmetricJwt);                     // Asymmetric signed JWT

Suivez ensuite les étapes ci-dessus pour importer le certificat sous Windows et configurer le site private key certificate name :

Authentification JWT signée

En choisissant JWT Authentication, l' agent Bridge envoie un message signed JSON Web Token (JWT) au service web de l'agent externe.

Exemple d'en-tête

{
  "host": "localhost:8555",
  "user-agent": "Go-http-client/1.1",
  "transfer-encoding": "chunked",
  "accept": "application/json",
  "authorization": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE2NjUxMTAyMjcsImlzcyI6IkJyaWRnZUFnZW50Iiwic3ViIjoic3ViampqIn0.FYcDCwMdQA4Ibx17hPvrfrpnUAYe6sB_bTtfDI2PA2A",
  "content-type": "application/json",
  "accept-encoding": "gzip"
}

Activation de l'authentification JWT signée symétriquement dans l'exemple d'application

Décommenter l'intergiciel symmetricJwt

// Authentication (uncomment desired)
// app.use(basicAuthen);                       // Basic Auth
// app.use(mtls);                              // MTLS
app.use(symmetricJwt);                      // Symmetric signed JWT
// app.use(asymmetricJwt);                     // Asymmetric signed JWT

Définition des variables .env pour l'authentification Symmetric Signed JWT

Ouvrez .env à la racine de votre répertoire de projet et définissez la clé secrète attendue, le sujet et le préfixe du JWT signé.

# Symmetric JWT variables
SYMMETRIC_JWT_SECRET_KEY=mySuperSecret
SYMMETRIC_JWT_SUBJECT=JwtAuth
SYMMETRIC_JWT_PREFIX='Bearer '

CONFIGURATION DE L'AGENT D'IDENTITÉ POUR LE JWT SYMÉTRIQUE SIGNÉ

Ouvrez l'interface utilisateur de l'agent d'identité et sélectionnez JSON Web Token (JWT). Complétez les sections suivantes

Activation de l'authentification JWT à signature asymétrique dans l'exemple d'application

Décommenter l'intergiciel asymmetricJwt

// Authentication (uncomment desired)
// app.use(basicAuthen);                       // Basic Auth
// app.use(mtls);                              // MTLS
// app.use(symmetricJwt);                      // Symmetric signed JWT
app.use(asymmetricJwt);                     // Asymmetric signed JWT

Définition des variables .env pour l'authentification Asymmetric Signed JWT

Ouvrez .env à la racine de votre répertoire de projet et définissez la clé secrète attendue, le sujet et le préfixe du JWT signé.

# Asymmetric JWT variables
ASYMMETRIC_JWT_PUBLIC_CERTIFICATE_PATH='./certs/extauthn.client.crt'
ASYMMETRIC_JWT_SUBJECT=JwtAuth
ASYMMETRIC_JWT_ALGORITHM=RS256
ASYMMETRIC_JWT_PREFIX='Bearer '

Remarquez maintenant que nous spécifions le chemin d'accès au certificat public. En effet, nous utiliserons cette clé publique pour vérifier le JWT signé.

En conséquence, cela signifie que l' agent-relais devra utiliser la clé privée correspondante pour signer le JWT.

Importez la clé privée dans le keystore de Windows en exécutant powershell en tant qu'administrateur et en tapant la commande suivante en remplaçant C:\extauthn.client.p12 par le chemin d'accès à votre fichier extauthn.client.p12.

Import-PfxCertificate -FilePath C:\extauthn.client.p12 -CertStoreLocation Cert:\LocalMachine\My

Vous devriez obtenir un résultat semblable à celui qui suit :

   PSParentPath: Microsoft.PowerShell.Security\Certificate::LocalMachine\My

Thumbprint                                Subject
----------                                -------
8BEB4C0A77090F2BEDA49BCC0A57B03E8242540B  CN=extauthn.client, OU=SecurityDev, O=IBM, S=QLD, C=AU

Notez cette valeur Subject ( CN=extauthn.client, OU=SecurityDev, O=IBM, S=QLD, C=AU ) car vous devrez la spécifier en tant que Private key certificate name lors de la configuration de votre agent d'identité sur ISV.

CONFIGURATION DE L'AGENT D'IDENTITÉ POUR LE JWT SIGNÉ ASYMÉTRIQUEMENT

Ouvrez l'interface utilisateur de l'agent d'identité et sélectionnez JSON Web Token (JWT). Complétez les sections suivantes

authentification OAUTH

Le flux OAuth fonctionne en demandant à l' agent-relais d'effectuer un flux OAuth pour les informations d'identification du client contre un serveur d'autorisation OAuth (ISV est utilisé dans cet exemple). Le processus se déroule comme suit :

1. L' agent-relais envoie ses informations d'identification au serveur d'autorisation pour obtenir un jeton d'accès.
2. Le jeton d'accès est ensuite envoyé en tant que jeton Bearer dans un en-tête d'autorisation à votre service web
3. Votre service web confirme la validité de ce jeton web en utilisant le point de terminaison introspect du serveur OAuth.

Activation de l'authentification OAuth dans l'application d'exemple

Décommenter l'intergiciel OAuth

// Authentication (uncomment desired)
// app.use(basicAuthen);                       // Basic Auth
// app.use(mtls);                              // MTLS
// app.use(symmetricJwt);                      // Symmetric signed JWT
// app.use(asymmetricJwt);                     // Asymmetric signed JWT
app.use(oauth);                             // Oauth         

Créer un client API dans ISV

Pour utiliser cet exemple OAuth avec l'ISV, vous devez créer un client API.

Ne sélectionnez aucun droit.

Utilisez les sites client id et client secret de ce client API dans les étapes suivantes.

Définir les variables OAuth .env

Ouvrez le fichier .env à la racine du répertoire de votre projet et définissez les variables suivantes :

# OAuth Variables
OAUTH_CLIENT_ID=12345678-1234-1234-1234-123456789012
OAUTH_CLIENT_SECRET=abcd1234
OAUTH_INTROSPECT_URL=https://tenant.verify.ibm.com/v1.0/endpoint/default/introspect

Configuration d'OAuth dans l' Web UI agent d'identité

Les paramètres de l'agent d'identité sont utilisés par l' agent de liaison pour communiquer avec votre service web. Saisissez les paramètres suivants

Installation du certificat racine sur la machine Windows

Pour que l' agent bridge sache qu'il doit faire confiance au certificat TLS présenté par votre service web, vous devez importer le certificat extauthn.caroot.crt dans le magasin de clés racine sous Windows.

Pour ce faire, exécutez powershell en tant qu'administrateur et tapez la commande suivante, en remplaçant C:\extauthn.caroot.crt par le chemin d'accès à votre fichier extauthn.caroot.crt

Import-Certificate -FilePath C:\extauthn.caroot.crt -CertStoreLocation Cert:\LocalMachine\root