Authentification JWT

Aperçu

L’authentification JWT permet d’appeler l’API Corgea avec des tokens Bearer émis directement par votre fournisseur d’identité (IdP), tel que Microsoft Entra ID ou Okta, au lieu d’utiliser un token d’API Corgea propre à un utilisateur. Cette approche est recommandée pour les intégrations système à système (pipelines CI/CD, scanners automatisés, outils internes) lorsque vous souhaitez :

associer les tokens à un principal de service ou à une inscription d’application plutôt qu’à un compte utilisateur ;
confier à votre IdP le contrôle de la durée de vie et du scope des tokens ;
centraliser leur révocation dans votre IdP, sans intervenir dans Corgea.

Un token d’API Corgea est toujours associé à un utilisateur. Si cet utilisateur quitte l’entreprise ou si son compte est désactivé, toute automatisation qui utilise son token cesse de fonctionner. L’authentification JWT dissocie entièrement l’authentification des comptes utilisateur.

Fonctionnement

Votre système demande un token d’accès à votre IdP avec les identifiants du client (ID client et secret).
L’IdP renvoie un JWT signé contenant des claims tels que iss (émetteur) et aud (audience).
Votre système transmet ce token en tant que token Bearer dans l’en-tête Authorization lors de l’appel à l’API Corgea.
Corgea valide la signature du token avec les clés publiques de l’IdP et vérifie que les claims iss, aud et appid/cid correspondent à la configuration enregistrée.

Utiliser JWT avec la CLI Corgea

Vous pouvez fournir directement un token d’accès JWT lors de la connexion avec la CLI :

corgea login YOUR_JWT_TOKEN

Vous pouvez également le définir dans une variable d’environnement :

export CORGEA_TOKEN="your-jwt-access-token"
corgea login

$env:CORGEA_TOKEN="your-jwt-access-token"
corgea login

Configurer l’authentification JWT dans Corgea

Accédez à Paramètres → Intégrations, puis cliquez sur + Ajouter dans la section JWT Auth.

Formulaire d’ajout d’une configuration JWT Auth dans Corgea

Remplissez les champs suivants :

Champ	Description
Nom	Un libellé descriptif pour cette configuration (par exemple, `Entra CICD Pipeline`).
Émetteur	URL de l’émetteur du token ; doit correspondre au claim `iss` du token d’accès.
Audience	Doit correspondre au claim `aud` du token d’accès.
ID d’application autorisés	Un ID client par ligne, correspondant à une application autorisée à utiliser cette configuration.

Utilisez jwt.io pour décoder un token d’accès émis par votre IdP et vérifier les valeurs exactes de iss, aud et appid/cid avant de remplir ce formulaire.

Valeurs spécifiques au fournisseur :

Émetteur Entra ID: https://sts.windows.net/{your-tenant-id}/
Audience Entra ID: URI de l’ID d’application (par exemple, api://{client_id}), défini dans Exposer une API dans Entra
Émetteur Okta: https://{domain}.okta.com/oauth2/default
Audience Okta: api://default (ou l’audience du serveur d’autorisation personnalisé)

Configurer Microsoft Entra ID

Inscrire une application dans Entra

Dans le portail Azure, accédez à Microsoft Entra ID → Inscriptions d’applications → Nouvelle inscription. Donnez à l’application un nom explicite (par exemple, corgea-cicd), puis inscrivez-la.

Exposer une API et définir l’URI de l’ID d’application

Dans l’inscription de votre application, accédez à Exposer une API. Définissez ou confirmez l’URI de l’ID d’application ; cette valeur devient le claim aud des tokens émis pour l’application.

Copiez l’URI d’identifiant d’application (par exemple, api://5d63c8f0-c9a8-4195-90ee-a9e27e4510b8) ; vous la saisirez comme Audience dans Corgea.

Créer un secret client

Accédez à Certificats et secrets → Nouveau secret client. Ajoutez une description et définissez une date d’expiration, puis cliquez sur Ajouter.

Ajouter un secret client dans Microsoft Entra

Copiez immédiatement la Valeur du secret : elle n’est affichée qu’une fois. Conservez-la en lieu sûr, par exemple dans le gestionnaire de secrets de votre CI/CD.

Demander un token d’accès

Votre système demande un token à Entra avec le flux d’identifiants client :

curl -X POST \
  https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/token \
  -d "grant_type=client_credentials" \
  -d "client_id={client-id}" \
  -d "client_secret={client-secret}" \
  -d "scope=api://{client-id}/.default"

Invoke-RestMethod -Method Post `
  -Uri "https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/token" `
  -Body @{
    grant_type    = "client_credentials"
    client_id     = "{client-id}"
    client_secret = "{client-secret}"
    scope         = "api://{client-id}/.default"
  }

La réponse contient un access_token. Transmettez-le comme token Bearer lors de l’appel à Corgea :

curl -H "Authorization: Bearer {access_token}" https://www.corgea.app/api/...

Invoke-RestMethod -Uri "https://www.corgea.app/api/..." `
  -Headers @{ Authorization = "Bearer {access_token}" }

Pour un déploiement privé, remplacez https://www.corgea.app par https://your_instance.corgea.app.

Enregistrer la configuration dans Corgea

Dans le formulaire Ajouter une configuration JWT Auth de Corgea, saisissez :

Émetteur: https://sts.windows.net/{your-tenant-id}/
Audience: l’URI de l’ID d’application de l’étape 2 (par exemple, api://5d63c8f0-...)
ID d’application autorisés: l’ID d’application (client) de votre inscription d’application

Cliquez sur Ajouter pour enregistrer.

Tester avec Postman

Si vous préférez une interface graphique à curl, vous pouvez tester directement dans Postman la demande de token et l’appel à l’API. Importer une commande curl Postman peut convertir en requête n’importe quelle commande curl ci-dessus. Cliquez sur Import en haut à gauche, collez la commande : Postman renseigne automatiquement la méthode, l’URL, les en-têtes et le corps.

Importation d’une commande curl dans Postman

Demander un token d’accès Renseignez tenant-id, client_id, client_secret et scope dans le corps, puis envoyez la requête. Copiez la valeur access_token de la réponse.

Demander un token d’accès dans Postman avec des identifiants client

Appeler l’API Corgea avec le token Créez une requête vers l’endpoint Corgea. Dans l’onglet Authorization, définissez le type sur Bearer Token et collez le access_token.

Appeler l’API Corgea avec un token Bearer dans Postman

Si votre entreprise restreint les accès réseau sortants, vous devrez peut-être configurer un proxy. Dans Postman, accédez à Settings → Proxy et ajoutez le proxy de votre entreprise. Pour curl, définissez la variable d’environnement HTTPS_PROXY ou indiquez --proxy https://your-proxy:port.

Vérifier votre token

Utilisez jwt.io pour décoder un token d’accès avant de configurer Corgea. Collez le token dans le debugger et examinez le payload décodé pour confirmer les valeurs iss, aud et appid.

Décoder un token JWT sur jwt.io pour vérifier les claims iss et aud

Les champs aud et iss mis en évidence correspondent exactement aux valeurs vérifiées par Corgea lors de la validation des requêtes entrantes.

Dépannage

401 Unauthorized : décodez votre token sur jwt.io et vérifiez que iss, aud et appid correspondent exactement aux valeurs de votre configuration JWT Auth dans Corgea.
Token rejeté après rotation : si vous avez renouvelé votre secret client, mettez à jour sa valeur dans votre environnement CI/CD. La configuration Corgea ne change pas, car elle valide les claims du token, et non le secret.
Environnements multiples : créez dans Corgea une configuration JWT Auth distincte pour chaque application ou environnement (par exemple, staging et production), avec des inscriptions d’application et des ID client différents.

Problèmes de connectivité réseau

Si la demande de token ou l’appel à l’API échoue avec une erreur de connexion, utilisez ces commandes pour déterminer si un pare-feu ou un proxy bloque le trafic.

# Check DNS resolution
nslookup login.microsoftonline.com
nslookup www.corgea.app

# Check TCP connectivity on port 443
nc -zv login.microsoftonline.com 443
nc -zv www.corgea.app 443

# Trace the network path
traceroute login.microsoftonline.com

# Test with verbose curl output (shows TLS handshake and redirect chain)
curl -v https://login.microsoftonline.com

# Test through a proxy if required
curl -v --proxy https://your-proxy:port https://login.microsoftonline.com

# Check DNS resolution
Resolve-DnsName login.microsoftonline.com
Resolve-DnsName www.corgea.app

# Check TCP connectivity on port 443
Test-NetConnection -ComputerName login.microsoftonline.com -Port 443
Test-NetConnection -ComputerName www.corgea.app -Port 443

# Trace the network path
tracert login.microsoftonline.com

# Test with verbose curl output
curl.exe -v https://login.microsoftonline.com

# Test through a proxy if required
curl.exe -v --proxy https://your-proxy:port https://login.microsoftonline.com

Si le test de connexion TCP échoue ou si traceroute s’arrête sur un saut interne, demandez à votre équipe réseau ou sécurité d’autoriser les connexions HTTPS sortantes (port 443) vers login.microsoftonline.com et www.corgea.app.

Bien démarrer

Fonctionnalités principales

Intégrations

Outils et utilitaires

Versions

Confiance et conformité