Partager via

Configurer l’authentification JWT personnalisée (Okta, Auth0)

Le générateur d’API de données prend en charge les fournisseurs d’identité tiers via le fournisseur d’authentification personnalisé. Utilisez cette approche lorsque votre organisation utilise Okta, Auth0 ou un autre fournisseur d’identité conforme à OAuth 2.0/OpenID Connect.

Flux d’authentification

Avec un fournisseur d’identité personnalisé, votre application cliente gère l’authentification utilisateur, puis envoie le jeton d’accès au générateur d’API de données :

Illustration du flux d’authentification JWT personnalisé avec un fournisseur d’identité tiers.

Phase Que se passe-t-il ?
Authentification de l’utilisateur L’utilisateur se connecte via le fournisseur d’identité (Okta, Auth0, etc.)
Acquisition de jetons L’application cliente reçoit un jeton d’accès du fournisseur d’identité
Appel d’API Le client envoie le jeton à DAB dans l’en-tête Authorization
Validation DAB valide le JWT (émetteur, audience, signature)
Autorisation DAB extrait les rôles et évalue les autorisations

Prerequisites

  • Un compte avec votre fournisseur d’identité (Okta, Auth0, etc.)
  • Une application enregistrée dans votre fournisseur d’identité
  • Interface CLI du générateur d’API de données installée (guide d’installation)
  • Un existant dab-config.json avec au moins une entité

Référence rapide

Réglage Valeur
Provider Custom
Obligatoire pour la validation iss, , audexp, signature valide
Obligatoire pour l’autorisation roles revendication contenant le rôle sélectionné
En-tête de jeton Authorization: Bearer <token>
Type de revendication de rôle roles (fixe, non configurable)
En-tête de sélection de rôle X-MS-API-ROLE

Étape 1 : Configurer votre fournisseur d’identité

Les étapes exactes dépendent de votre fournisseur. Voici les valeurs clés dont vous avez besoin :

Valeurs à collecter

Valeur Comment y accéder Utilisé pour
URL de l’émetteur Documentation du fournisseur ou point de terminaison de métadonnées OAuth DAB jwt.issuer (utilisé comme autorité JWT)
Public ciblé ID client de votre application ou identificateur d’API personnalisé DAB jwt.audience

Note

DAB utilise la configuration jwt.issuer en tant qu’autorité JWT. Les clés de signature sont découvertes automatiquement via les métadonnées OpenID Connect standard (généralement <issuer>/.well-known/openid-configuration).

Exemple Okta

  1. Connectez-vous à la console d’administration Okta.
  2. Accédez aux applications>applications.
  3. Créez ou sélectionnez une application.
  4. Notez l’ID client (à utiliser comme public).
  5. Votre émetteur est généralement https://<your-domain>.okta.com.

Exemple Auth0

  1. Connectez-vous au tableau de bord Auth0.
  2. Accédez à Applications>API.
  3. Créez ou sélectionnez une API.
  4. Notez l’identificateur (à utiliser comme public cible).
  5. Votre émetteur est https://<your-tenant>.auth0.com/.

Important

Le générateur d'API de données utilise un type de revendication fixe de roles pour l'autorisation basée sur les rôles. Cette valeur ne peut pas être configurée. Si votre fournisseur d’identité émet des rôles dans une autre déclaration (par exemple, groups ou permissions), vous devez configurer votre fournisseur pour qu'il émette également une déclaration roles, ou utiliser une action post-connexion pour copier des valeurs dans une déclaration roles.

Étape 2 : Configurer le générateur d’API de données

Définissez le fournisseur d’authentification sur Custom et configurez les paramètres JWT :

Interface de ligne de commande (CLI)

# Set the authentication provider
dab configure \
  --runtime.host.authentication.provider Custom

# Set the expected audience
dab configure \
  --runtime.host.authentication.jwt.audience "<your-api-identifier>"

# Set the expected issuer
dab configure \
  --runtime.host.authentication.jwt.issuer "https://<your-issuer>/"

Configuration résultante

{
  "runtime": {
    "host": {
      "authentication": {
        "provider": "Custom",
        "jwt": {
          "audience": "<your-api-identifier>",
          "issuer": "https://<your-issuer>/"
        }
      }
    }
  }
}

Étape 3 : Configurer les autorisations d’entité

Définissez les autorisations pour les rôles que votre fournisseur d’identité attribue :

Interface de ligne de commande (CLI)

# Allow authenticated users to read
dab update Book \
  --permissions "authenticated:read"

# Allow users with 'admin' role full access
dab update Book \
  --permissions "admin:*"

Configuration résultante

{
  "entities": {
    "Book": {
      "source": "dbo.Books",
      "permissions": [
        {
          "role": "authenticated",
          "actions": ["read"]
        },
        {
          "role": "admin",
          "actions": ["*"]
        }
      ]
    }
  }
}

Étape 4 : Configurer des rôles dans votre fournisseur d’identité

DAB s'attend à des rôles dans une roles réclamation. Configurez votre fournisseur d’identité pour inclure cette revendication.

Okta : Ajouter des groupes en tant que rôles

  1. Dans la console d’administration Okta, accédez àl’API>.
  2. Sélectionnez votre serveur d’autorisation.
  3. Accédez à l’onglet Revendications .
  4. Ajoutez une revendication :
    • Nom : roles
    • Inclure dans le type de jeton : Jeton d’accès
    • Type de valeur : Groupes
    • Filtre : sélectionnez les groupes à inclure

Authentification0 : Ajouter des rôles avec une action

  1. Dans le tableau de bord Auth0, accédez à labibliothèque>.
  2. Créez une action (déclencheur post-connexion).
  3. Ajoutez du code pour inclure des rôles :
exports.onExecutePostLogin = async (event, api) => {
  const roles = event.authorization?.roles || [];
  if (roles.length > 0) {
    api.accessToken.setCustomClaim('roles', roles);
  }
};
  1. Déployez l’action et ajoutez-la à votre flux de connexion.

Conseil / Astuce

Pour obtenir des instructions détaillées sur la configuration des revendications JWT avec Okta, consultez Implémentation de revendications JWT avancées avec le Kit de développement logiciel (SDK) d’Okta.

Étape 5 : Tester la configuration

  1. Démarrer le générateur d’API de données :

    dab start

  2. Obtenez un jeton de votre fournisseur d’identité. Utilisez le Kit de développement logiciel (SDK) de votre fournisseur ou un outil comme Postman.

  3. Inspectez le jeton à jwt.io pour vérifier :

    • La aud assertion correspond à votre audience configurée
    • La iss revendication correspond à votre émetteur configuré
    • La roles revendication contient les valeurs attendues

  4. Appelez l’API :

    curl -X GET "http://localhost:5000/api/Book" \
  -H "Authorization: Bearer <your-token>"

  5. Pour utiliser un rôle personnalisé, incluez l’en-tête X-MS-API-ROLE :

    curl -X GET "http://localhost:5000/api/Book" \
  -H "Authorization: Bearer <your-token>" \
  -H "X-MS-API-ROLE: admin"

Détails de la validation JWT

Le générateur d’API de données valide ces aspects du JWT :

Vérifier Descriptif
Signature Validé à l’aide de clés de signature découvertes via l’autorité configurée jwt.issuer (métadonnées OpenID Connect / JWKS)
Émetteur Doit correspondre exactement à la configuration de jwt.issuer
Public ciblé Doit correspondre exactement à la configuration de jwt.audience
Échéance Le jeton ne doit pas être expiré (exp revendication)
Pas avant Le jeton doit être valide (nbf revendication, le cas échéant)

Résolution des problèmes

Symptôme Cause potentielle Solution
401 Unauthorized Incompatibilité de l’émetteur Vérifiez que la iss revendication correspond exactement (y compris le slash final)
401 Unauthorized Incompatibilité de l’audience Vérifiez que la aud revendication correspond à votre valeur configurée
401 Unauthorized Le jeton a expiré Acquérir un nouveau jeton
401 Unauthorized Métadonnées indisponibles Vérifier que DAB peut atteindre <issuer>/.well-known/openid-configuration
403 Forbidden Le rôle n'est pas présent dans le jeton. Ajouter le rôle à votre configuration IdP
403 Forbidden Revendication de rôles manquante Configurer votre fournisseur d’identité pour inclure une roles revendication
403 Forbidden Nom de la revendication incorrecte DAB utilise le type roles de demande (fixe, non configurable)

Important

DAB utilise actuellement le type roles de revendication pour toutes les vérifications de rôle. Cette valeur est codée en dur et ne peut pas être modifiée en groups, permissionsou d’autres noms de revendication. Configurez votre fournisseur d’identité pour émettre des rôles dans une revendication nommée roles.

Formats d’émetteur courants

Provider Format de l’émetteur
Okta https://<domain>.okta.com ou https://<domain>.okta.com/oauth2/default
Auth0 https://<tenant>.auth0.com/ (notez la barre oblique de fin)
Azure AD B2C https://<tenant>.b2clogin.com/<tenant-id>/v2.0/
Keycloak https://<host>/realms/<realm>

Exemple de configuration complet

Configuration Okta

{
  "$schema": "https://github.com/Azure/data-api-builder/releases/latest/download/dab.draft.schema.json",
  "data-source": {
    "database-type": "mssql",
    "connection-string": "@env('SQL_CONNECTION_STRING')"
  },
  "runtime": {
    "host": {
      "authentication": {
        "provider": "Custom",
        "jwt": {
          "audience": "0oa1234567890abcdef",
          "issuer": "https://dev-12345.okta.com"
        }
      }
    }
  },
  "entities": {
    "Book": {
      "source": "dbo.Books",
      "permissions": [
        {
          "role": "authenticated",
          "actions": ["read"]
        },
        {
          "role": "editor",
          "actions": ["create", "read", "update"]
        }
      ]
    }
  }
}

Configuration d’authentification

{
  "$schema": "https://github.com/Azure/data-api-builder/releases/latest/download/dab.draft.schema.json",
  "data-source": {
    "database-type": "mssql",
    "connection-string": "@env('SQL_CONNECTION_STRING')"
  },
  "runtime": {
    "host": {
      "authentication": {
        "provider": "Custom",
        "jwt": {
          "audience": "https://my-api.example.com",
          "issuer": "https://my-tenant.auth0.com/"
        }
      }
    }
  },
  "entities": {
    "Book": {
      "source": "dbo.Books",
      "permissions": [
        {
          "role": "authenticated",
          "actions": ["read"]
        },
        {
          "role": "admin",
          "actions": ["*"]
        }
      ]
    }
  }
}

Contenu connexe

  • Last updated on