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 usando la convalida del token Web JSON (JWT). 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:

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

Passaggio 1: Configurare il provider di identità

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

Valori da raccogliere

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

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

REM Set the authentication provider
dab configure ^
  --runtime.host.authentication.provider Custom

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

REM 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:*"

REM Allow authenticated users to read
dab update Book ^
  --permissions "authenticated:read"

REM 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

Auth0 richiede che i claim personalizzati utilizzino nomi namespaced resistenti alle collisioni (ad esempio, https://example.com/roles). Le attestazioni senza spazio dei nomi che entrano in conflitto con i nomi riservati vengono escluse dal token senza notifica. Per altre informazioni, vedere Creare attestazioni personalizzate nella documentazione di Auth0.

Data API Builder si aspetta il nome esatto del claim roles, non una variante con namespace. Se Auth0 accetta un claim senza spazio dei nomi roles dipende dalla configurazione del tenant.

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);
     }
   };
   

4. Distribuire l'Azione e aggiungerla al flusso di autenticazione.

5. Verificare il token di accesso decodificato in jwt.io e verificare che l'attestazione roles sia presente.

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:

Risoluzione dei problemi

Formati comuni dell'autorità emittente

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

• Panoramica dell'autorizzazione
• Configurare l'autenticazione di Microsoft Entra ID
• Configurare l'autenticazione del simulatore per i test
• Informazioni di riferimento sulla configurazione del runtime