Dela via

Konfigurera anpassad JWT-autentisering (Okta, Auth0)

Data API Builder stöder identitetsprovidrar från tredje part via den anpassade autentiseringsprovidern. Använd den här metoden när din organisation använder Okta, Auth0 eller någon annan OAuth 2.0/OpenID Connect-kompatibel identitetsprovider.

Autentiseringsflöde

Med en anpassad identitetsprovider hanterar klientappen användarautentisering och skickar sedan åtkomsttoken till Data API Builder:

Bild av det anpassade JWT-autentiseringsflödet med en identitetsprovider från tredje part.

Phase Vad händer
Användarautentisering Användaren loggar in via identitetsprovidern (Okta, Auth0 osv.)
Tokenförvärv Klientappen tar emot en åtkomsttoken från IdP:t
API-anrop Klienten skickar token till DAB i Authorization rubriken
Validering DAB validerar JWT (utfärdare, målgrupp, signatur)
Behörighet DAB extraherar roller och utvärderar behörigheter

Förutsättningar

  • Ett konto med din identitetsprovider (Okta, Auth0 osv.)
  • En applikation registrerad i din identitetsleverantör
  • Cli för data-API-byggare installerad (installationsguide)
  • En befintlig dab-config.json med minst en entitet

Snabbreferens

Inställning Värde
Provider Custom
Krävs för validering iss, aud, exp, giltig signatur
Krävs för auktorisering roles anspråk som innehåller den valda rollen
Tokenrubrik Authorization: Bearer <token>
Rollanspråkstyp roles (fastställd, inte konfigurerbar)
Rubrik för val av roll X-MS-API-ROLE

Steg 1: Konfigurera din identitetsprovider

De exakta stegen beror på leverantören. Här är de nyckelvärden som du behöver:

Värden att samla in

Värde Här hittar du den Används för
Utfärdar-URL Leverantörens dokumentation eller OAuth-metadataslutpunkt DAB jwt.issuer (används som JWT-myndighet)
målgrupp Programmets klient-ID eller en anpassad API-identifierare DAB jwt.audience

Anmärkning

DAB använder den konfigurerade jwt.issuer som JWT-Authority. Signeringsnycklar identifieras automatiskt via OpenID Connect-standardmetadata (vanligtvis <issuer>/.well-known/openid-configuration).

Okta exempel

  1. Logga in på okta-administratörskonsolen.
  2. Gå till Program>Program.
  3. Skapa eller välj ett program.
  4. Observera klient-ID :t (används som målgrupp).
  5. Utfärdaren är vanligtvis https://<your-domain>.okta.com.

Auth0-exempel

  1. Logga in på instrumentpanelen Auth0.
  2. Gå till Program>API:er.
  3. Skapa eller välj ett API.
  4. Observera identifieraren (använd som målgrupp).
  5. Utfärdaren är https://<your-tenant>.auth0.com/.

Viktigt!

Data API Builder använder en fast anspråkstyp roles för rollbaserad auktorisering. Det går inte att konfigurera det här värdet. Om din identitetsprovider genererar roller i ett annat anspråk (till exempel groups eller permissions) måste du konfigurera providern att även generera ett roles anspråk eller använda en åtgärd efter inloggningen för att kopiera värden till ett roles anspråk.

Steg 2: Konfigurera data-API-byggare

Ange autentiseringsprovidern till Custom och konfigurera JWT-inställningarna:

Kommandoradsgränssnitt (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>/"

Resulterande konfiguration

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

Steg 3: Konfigurera entitetsbehörigheter

Definiera behörigheter för de roller som identitetsprovidern tilldelar:

Kommandoradsgränssnitt (CLI)

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

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

Resulterande konfiguration

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

Steg 4: Konfigurera roller i din identitetsprovider

DAB förväntar sig roller i ett roles anspråk. Konfigurera identitetsprovidern så att den inkluderar det här anspråket.

Okta: Lägga till grupper som roller

  1. I okta-administratörskonsolen går du till Säkerhets-API>.
  2. Välj din auktoriseringsserver.
  3. Gå till fliken Anspråk .
  4. Lägg till ett anspråk:
    • Namn: roles
    • Inkludera i tokentyp: Åtkomsttoken
    • Värdetyp: Grupper
    • Filter: Välj de grupper som ska inkluderas

Auth0: Lägga till roller med en åtgärd

  1. I instrumentpanelen Auth0 går du till Åtgärdsbibliotek>.
  2. Skapa en ny åtgärd (utlösare efter inloggning).
  3. Lägg till kod för att inkludera roller:
exports.onExecutePostLogin = async (event, api) => {
  const roles = event.authorization?.roles || [];
  if (roles.length > 0) {
    api.accessToken.setCustomClaim('roles', roles);
  }
};
  1. Distribuera åtgärden och lägg till den i ditt inloggningsflöde.

Tips/Råd

Detaljerad vägledning om hur du konfigurerar JWT-anspråk med Okta finns i Implementera avancerade JWT-anspråk med Oktas SDK.

Steg 5: Testa konfigurationen

  1. Starta data-API-byggare:

    dab start

  2. Hämta en token från din identitetsprovider. Använd leverantörens SDK eller ett verktyg som Postman.

  3. Kontrollera token vid jwt.io för att verifiera:

    • Anspråket aud matchar din konfigurerade målgrupp
    • Anspråket iss matchar din konfigurerade utfärdare
    • Anspråket roles innehåller de förväntade värdena

  4. Anropa API:et:

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

  5. Om du vill använda en anpassad roll inkluderar du X-MS-API-ROLE rubriken:

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

JWT-verifieringsinformation

Data API Builder validerar dessa aspekter av JWT:

Check Description
Underskrift Verifierad med signeringsnycklar som identifierats via den konfigurerade jwt.issuer auktoriteten (OpenID Connect metadata / JWKS)
Utfärdare Måste exakt matcha jwt.issuer konfigurationen
målgrupp Måste matcha konfigurationen exakt jwt.audience
förfallodatum Token får inte ha upphört att gälla (exp anspråk)
Inte tidigare Token måste vara giltig (nbf påstående, om det finns)

Felsökning

Symtom Möjlig orsak Lösning
401 Unauthorized Felmatchning av utfärdare Kontrollera att iss anspråket matchar exakt (inklusive avslutande snedstreck)
401 Unauthorized Målgruppsmissmatch Kontrollera att anspråket aud matchar ditt konfigurerade värde
401 Unauthorized Token har upphört att gälla Hämta en ny token
401 Unauthorized Metadata är inte tillgängliga Se till att DAB kan nå <issuer>/.well-known/openid-configuration
403 Forbidden Rollen finns inte i token Lägg till rollen i IdP-konfigurationen
403 Forbidden Rollkrav saknas Konfigurera din IdP för att inkludera ett roles anspråk
403 Forbidden Fel anspråksnamn DAB använder anspråkstyp roles (fast, ej konfigurerbar)

Viktigt!

DAB använder för närvarande anspråkstypen roles för alla rollkontroller. Det här värdet är hårdkodat och kan inte ändras till groups, permissionseller andra anspråksnamn. Konfigurera identitetsleverantören för att tilldela roller i ett anspråk med namnet roles.

Vanliga format för utfärdare

Provider Issuer-format
Okta https://<domain>.okta.com eller https://<domain>.okta.com/oauth2/default
Auth0 https://<tenant>.auth0.com/ (observera det avslutande snedstrecket)
Azure AD B2C https://<tenant>.b2clogin.com/<tenant-id>/v2.0/
Keycloak https://<host>/realms/<realm>

Komplett konfigurationsexempel

Okta-konfiguration

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

Auth0-konfiguration

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

Relaterat innehåll

  • Last updated on