Condividi tramite

Configurare l'autenticazione JWT personalizzata (Okta, Auth0)

Il generatore di API dati supporta provider di identità di terze parti tramite il provider di autenticazione personalizzato. Usare questo approccio quando l'organizzazione usa Okta, Auth0 o un altro provider di identità conforme a OAuth 2.0/OpenID Connect.

Flusso di autenticazione

Con un provider di identità personalizzato, l'app client gestisce l'autenticazione utente e quindi invia il token di accesso al generatore di API dati:

Illustrazione del flusso di autenticazione JWT personalizzato con un provider di identità di terze parti.

Phase Che succede
Autenticazione utente L'utente accede tramite il provider di identità (Okta, Auth0 e così via)
Acquisizione di token L'app client riceve un token di accesso dal provider di identità (IdP)
Chiamata API Il client invia il token a DAB nell'intestazione Authorization
Validation DAB valida il token JWT (emittente, pubblico, firma)
Autorizzazione DAB estrae i ruoli e valuta le autorizzazioni

Prerequisiti

  • Un account con il provider di identità (Okta, Auth0 e così via)
  • Un'applicazione registrata nel provider di identità
  • CLI di Data API Builder installata (guida all'installazione)
  • Un dab-config.json esistente con almeno un'entità

Riferimento rapido

Impostazione Value
Provider Custom
Obbligatorio per la convalida iss, audexp, firma valida
Obbligatorio per l'autorizzazione roles attestazione contenente il ruolo selezionato
Intestazione del token Authorization: Bearer <token>
Tipo di attestazione del ruolo roles (fisso, non configurabile)
Intestazione di selezione ruolo X-MS-API-ROLE

Passaggio 1: Configurare il provider di identità

I passaggi esatti dipendono dal provider. Ecco i valori chiave necessari:

Valori da raccogliere

Value Dove trovarlo Utilizzo
URL dell'emittente Documentazione del provider o endpoint di metadati OAuth DAB jwt.issuer (usato come autorità JWT)
Destinatari ID client dell'applicazione o identificatore DELL'API personalizzato DAB jwt.audience

Annotazioni

DAB usa l'oggetto configurato jwt.issuer come JWT Autorità. Le chiavi di firma vengono individuate automaticamente tramite i metadati standard di OpenID Connect (di <issuer>/.well-known/openid-configurationsolito).

Esempio Okta

  1. Accedere alla console di amministrazione di Okta.
  2. Passare ad Applicazioni>.
  3. Creare o selezionare un'applicazione.
  4. Prendere nota dell'ID client (usare come gruppo di destinatari).
  5. L'autorità emittente è https://<your-domain>.okta.com in genere.

Esempio di Auth0

  1. Accedere al dashboard Auth0.
  2. Naviga su Applicazioni>API.
  3. Creare o selezionare un'API.
  4. Prendere nota dell'identificatore (usare come gruppo di destinatari).
  5. L'autorità emittente è https://<your-tenant>.auth0.com/.

Importante

Il generatore di API dati usa un tipo di attestazione fisso di roles per l'autorizzazione basata su ruoli. Questo valore non può essere configurato. Se il provider di identità genera ruoli in un'attestazione diversa, ad esempio groups o permissions, è necessario configurare il provider per generare anche un'attestazione roles oppure usare un'azione di post-accesso per copiare i valori in un'attestazione roles .

Passaggio 2: Configurare il generatore di API dati

Impostare il provider di autenticazione su Custom e configurare le impostazioni JWT:

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>/"

Configurazione risultante

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

Passaggio 3: Configurare le autorizzazioni per le entità

Definire le autorizzazioni per i ruoli assegnati dal provider di identità:

CLI

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

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

Configurazione risultante

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

Passaggio 4: Configurare i ruoli nel provider di identità

DAB prevede ruoli in una roles richiesta. Configurare il provider di identità per includere questa attestazione.

Okta: Aggiungere gruppi come ruoli

  1. Nella console di amministrazione di Okta passareall'API>.
  2. Selezionare il server di autorizzazione.
  3. Passare alla scheda Attestazioni .
  4. Aggiungere un'attestazione:
    • Nome: roles
    • Includere nel tipo di token: Token di accesso
    • Tipo di valore: Gruppi
    • Filtro: selezionare i gruppi da includere

Auth0: Aggiungere ruoli con un'azione

  1. Nella dashboard Auth0, vai su Azioni>Libreria.
  2. Creare una nuova Azione (Post Login trigger).
  3. Aggiungere il codice per includere i ruoli:
exports.onExecutePostLogin = async (event, api) => {
  const roles = event.authorization?.roles || [];
  if (roles.length > 0) {
    api.accessToken.setCustomClaim('roles', roles);
  }
};
  1. Distribuire l'Azione e aggiungerla al flusso di autenticazione.

Suggerimento

Per indicazioni dettagliate sulla configurazione delle attestazioni JWT con Okta, vedere Implementazione di attestazioni JWT avanzate con OKTA SDK.

Passaggio 5: Testare la configurazione

  1. Avviare il generatore di API dati:

    dab start

  2. Acquisire un token dal provider di identità. Usare l'SDK del provider o uno strumento come Postman.

  3. Esaminare il token in jwt.io per verificare:

    • L'attestazione aud corrisponde al gruppo di destinatari configurato
    • La dichiarazione corrisponde al tuo emittente iss configurato
    • L'attestazione roles contiene i valori previsti

  4. Chiamare l'API:

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

  5. Per usare un ruolo personalizzato, includere l'intestazione X-MS-API-ROLE :

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

Dettagli di convalida JWT

Il generatore di API dati convalida questi aspetti del token JWT:

Controlla Description
firma Convalidato usando le chiavi di firma individuate tramite l'autorità configurata jwt.issuer (metadati OpenID Connect/JWKS)
Emittente Deve corrispondere esattamente alla jwt.issuer configurazione
Destinatari Deve corrispondere esattamente alla jwt.audience configurazione
Scadenza Il token non deve essere scaduto (exp attestazione)
Non prima Il token deve essere valido (nbf attestazione, se presente)

Risoluzione dei problemi

Sintomo Possibile causa Soluzione
401 Unauthorized Mancata corrispondenza del mittente Controllare che la dichiarazione iss corrisponda esattamente (inclusa la barra finale)
401 Unauthorized Discordanza del pubblico Controllare che l'attestazione aud corrisponda al valore configurato
401 Unauthorized Token scaduto Acquisire un nuovo token
401 Unauthorized Metadati non disponibili Assicurarsi che DAB possa raggiungere <issuer>/.well-known/openid-configuration
403 Forbidden Ruolo non nel token Aggiungere il ruolo alla configurazione IdP
403 Forbidden Richiesta ruoli mancante Configura il tuo IdP per includere un'attestazione roles
403 Forbidden Nome reclamo errato DAB utilizza il tipo di attestazione roles (fisso, non configurabile)

Importante

Attualmente, DAB utilizza il tipo di attestazione roles per tutti i controlli dei ruoli. Questo valore è codificato in modo fisso e non può essere modificato in groups, permissions o in altri nomi di dichiarazione. Configurare il provider di identità per generare ruoli in un'attestazione denominata roles.

Formati comuni dell'autorità emittente

Provider Formato emittente
Okta https://<domain>.okta.com o https://<domain>.okta.com/oauth2/default
Auth0 https://<tenant>.auth0.com/ (si noti la barra finale)
Azure AD B2C https://<tenant>.b2clogin.com/<tenant-id>/v2.0/
Keycloak https://<host>/realms/<realm>

Esempio di configurazione completo

Configurazione di 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"]
        }
      ]
    }
  }
}

Configurazione di Auth0

{
  "$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": ["*"]
        }
      ]
    }
  }
}

Contenuti correlati

  • Last updated on