Aangepaste JWT-verificatie configureren (Okta, Auth0)

Data API Builder ondersteunt id-providers van derden via de aangepaste verificatieprovider met behulp van JSON-webtokenvalidatie (JWT). Gebruik deze methode wanneer uw organisatie Okta, Auth0 of een andere OAuth 2.0/OpenID Connect-compatibele id-provider gebruikt.

Authenticatiestroom

Met een aangepaste id-provider verwerkt uw client-app gebruikersverificatie en verzendt het toegangstoken vervolgens naar Data API Builder:

Diagram van de aangepaste JWT-verificatiestroom met een externe id-provider.

Fase Wat gebeurt er?
Gebruikersverificatie Gebruiker meldt zich aan via de id-provider (Okta, Auth0, enzovoort)
Token ophalen Client-app ontvangt een toegangstoken van de IdP
API-aanroep Client verzendt het token naar DAB in de Authorization header
Validation DAB valideert de JWT (uitgever, doelgroep, handtekening)
Authorization DAB extraheert rollen en beoordeelt permissies

Vereiste voorwaarden

  • Een account met uw id-provider (Okta, Auth0, enzovoort)
  • Een toepassing die is geregistreerd in uw id-provider
  • Data API Builder CLI geïnstalleerd (installatiehandleiding)
  • Een bestaande dab-config.json met ten minste één entiteit

Snelzoekgids

Configuratie Waarde
Aanbieder Custom
Vereist voor validatie iss, , audexpgeldige handtekening
Vereist voor autorisatie roles claim die de geselecteerde rol bevat
Token-koptekst Authorization: Bearer <token>
Type roltoewijzing roles (opgelost, niet configureerbaar)
Koptekst voor rolselectie X-MS-API-ROLE

Stap 1: uw id-provider configureren

De exacte stappen zijn afhankelijk van uw provider. Dit zijn de belangrijkste waarden die u nodig hebt:

Te verzamelen waarden

Waarde Waar vind ik het? Gebruikt voor
URL van uitgever Documentatie van de provider of OAuth-metagegevens-eindpunt DAB jwt.issuer (gebruikt als JWT-autoriteit)
Audiëntie De client-id van uw toepassing of een aangepaste API-id DAB jwt.audience

Opmerking

DAB maakt gebruik van de geconfigureerde jwt.issuer als de JWT-autorisatie. Ondertekeningssleutels worden automatisch gedetecteerd via standaard Metagegevens van OpenID Connect (meestal <issuer>/.well-known/openid-configuration).

Okta-voorbeeld

  1. Meld u aan bij de Okta-beheerconsole.
  2. Navigeer naar Toepassingen>Toepassingen.
  3. Een toepassing maken of selecteren.
  4. Noteer de client-id (gebruik deze als doelgroep).
  5. Uw verlener is doorgaans https://<your-domain>.okta.com.

Voorbeeld van Auth0

  1. Meld u aan bij het Auth0-dashboard.
  2. Navigeer naar Toepassingen>API's.
  3. Een API maken of selecteren.
  4. Noteer de id (gebruik deze als doelgroep).
  5. Uw uitgever is https://<your-tenant>.auth0.com/.

Belangrijk

Data API Builder maakt gebruik van een vast claimtype voor autorisatie op basis van roles rollen. Deze waarde kan niet worden geconfigureerd. Als uw identiteitsprovider rollen verzendt in een andere claim (zoals groups of permissions), configureer deze dan zo dat deze ook een roles-claim verzendt. Gebruikers van Auth0 moeten het bekende conflict met naamruimten doornemen voordat ze verdergaan.

Stap 2: Data API Builder configureren

Stel de verificatieprovider in op Custom en configureer de JWT-instellingen.

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

Resulterende configuratie

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

Stap 3: Entiteitsmachtigingen configureren

Machtigingen definiëren voor de rollen die uw id-provider toewijst:

CLI

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

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

Resulterende configuratie

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

Stap 4: Rollen in uw id-provider configureren

DAB verwacht rollen bij een roles claim. Configureer uw id-provider om deze claim op te nemen.

Okta: Groepen toevoegen als rollen

  1. Ga in de Okta-beheerconsole naar de Beveiligings-API>.
  2. Selecteer uw autorisatieserver.
  3. Ga naar het tabblad Claims .
  4. Een claim toevoegen:
    • Naam: roles
    • Opnemen in tokentype: Toegangstoken
    • Waardetype: Groepen
    • Filter: Selecteer de groepen die u wilt opnemen

Verificatie0: rollen toevoegen met een actie

Auth0 vereist dat aangepaste claims botsingsbestendige namen met een naamruimte gebruiken (bijvoorbeeld https://example.com/roles). Niet-naamruimteclaims die botsen met gereserveerde namen, worden op de achtergrond uitgesloten van het token. Zie Aangepaste claims maken in de Auth0-documentatie voor meer informatie.

Data API Builder verwacht de exacte claimnaam roles, niet een variant met een naamruimte. Of Auth0 een niet-naamruimteclaim roles accepteert, is afhankelijk van uw tenantconfiguratie.

  1. Ga in het Auth0-dashboard naar Acties>Bibliotheek.

  2. Maak een nieuwe actie (trigger na aanmelding).

  3. Voeg code toe om rollen op te nemen:

    exports.onExecutePostLogin = async (event, api) => {
  const roles = event.authorization?.roles || [];
  if (roles.length > 0) {
    api.accessToken.setCustomClaim('roles', roles);
  }
};

  4. Implementeer de actie en voeg deze toe aan uw aanmeldingsstroom.

  5. Controleer het gedecodeerde toegangstoken op jwt.io en controleer of de roles claim aanwezig is.

Warning

Auth0 kan de claim zonder naamruimte roles stilzwijgend weglaten, afhankelijk van uw tenantinstellingen. Als de claim ontbreekt in het token, controleer Settings>Advanced in het Auth0-dashboard om te controleren of naamruimteafdwinging is ingeschakeld. Tenants waarvoor claims met een naamruimte zijn vereist, zijn momenteel niet compatibel met de rolgebaseerde autorisatie van Data API builder voor aangepaste rollen. De ingebouwde authenticated rollen en anonymous rollen werken nog steeds omdat ze niet afhankelijk zijn van een roles claim.

Aanbeveling

Voor gedetailleerde richtlijnen voor het configureren van JWT-claims, zie Aanpassen van tokens die door Okta zijn geretourneerd.

Stap 5: De configuratie testen

  1. Start Data API Builder:

    dab start

  2. Een token verkrijgen van uw id-provider. Gebruik de SDK van uw provider of een hulpprogramma zoals Postman.

  3. Controleer het token op jwt.io om het volgende te controleren:

    • De aud claim komt overeen met uw geconfigureerde doelgroep
    • De iss claim komt overeen met uw geconfigureerde verlener
    • De roles claim bevat de verwachte waarden

  4. Roep de API aan:

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

  5. Als u een aangepaste rol wilt gebruiken, neemt u de X-MS-API-ROLE header op:

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

JWT-validatiedetails

Data API Builder valideert deze aspecten van de JWT:

Controle Beschrijving
handtekening Gevalideerd met behulp van ondertekeningssleutels die zijn gedetecteerd via de geconfigureerde jwt.issuer instantie (OpenID Connect-metagegevens of JSON Web Key Set (JWKS))
Uitgever Moet exact overeenkomen met jwt.issuer de configuratie
Audiëntie Moet exact overeenkomen met jwt.audience de configuratie
Vervaldatum Token mag niet verlopen zijn (exp claim)
Niet eerder dan Token moet geldig zijn (nbf claim, indien aanwezig)

Troubleshooting

Symptoom Mogelijke oorzaak Solution
401 Unauthorized Verlener komt niet overeen Controleer of de iss claim precies overeenkomt (inclusief afsluitende slash)
401 Unauthorized Doelgroep komt niet overeen Controleer of de aud claim overeenkomt met uw geconfigureerde waarde
401 Unauthorized Token is verlopen Een nieuw token verkrijgen
401 Unauthorized Metagegevens zijn niet beschikbaar Zorg ervoor dat DAB kan <issuer>/.well-known/openid-configuration bereiken
403 Forbidden Rol niet in token De rol toevoegen aan uw IdP-configuratie
403 Forbidden Geen roles claim gevonden Uw IdP configureren om een roles claim op te nemen
403 Forbidden Verkeerde claimnaam DAB maakt gebruik van claimtype roles (vast, niet configureerbaar)
403 Forbidden Door Auth0 stilzwijgend genegeerde aangepaste claim Auth0 kan aangepaste claims zonder naamruimte negeren. Controleer of de roles claim bestaat in het gedecodeerde token op jwt.io. Zie Auth0: Rollen toevoegen met een actie

Belangrijk

Het claimtype roles is vastgelegd voor alle rolcontroles en kan niet worden gewijzigd. Configureer uw id-provider om een claim met de naam precies roleste verzenden. Auth0-gebruikers moeten het naamruimteconflict bekijken.

Algemene formaten voor issuers

Aanbieder Formaat van uitgever
Okta https://<domain>.okta.com of https://<domain>.okta.com/oauth2/default
Auth0 https://<tenant>.auth0.com/ (let op de afsluitende slash)
Azure AD B2C https://<tenant>.b2clogin.com/<tenant-id>/v2.0/
Keycloak https://<host>/realms/<realm>

Volledig configuratievoorbeeld

Okta-configuratie

{
  "$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-configuratie

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

Verwante inhoud

  • Last updated on