Delen via

Aangepaste JWT-verificatie configureren (Okta, Auth0)

Data API Builder ondersteunt id-providers van derden via de aangepaste verificatieprovider. 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:

Afbeelding van de aangepaste JWT-verificatiestroom met een id-provider van derden.

Phase 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
Provider Custom
Vereist voor validatie iss, , audexpgeldige handtekening
Vereist voor autorisatie roles claim met de geselecteerde rol
Token header 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 id-provider rollen verzendt in een andere claim (zoals groups of permissions), moet u uw provider configureren om ook een roles claim te verzenden of een actie na aanmelding gebruiken om waarden naar een roles claim te kopiëren.

Stap 2: Data API Builder configureren

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

CLI (Command Line Interface)

# 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 (Command Line Interface)

# 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

  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);
  }
};
  1. Implementeer de actie en voeg deze toe aan uw aanmeldingsstroom.

Aanbeveling

Zie Geavanceerde JWT-claims implementeren met okta voor gedetailleerde richtlijnen voor het configureren van JWT-claims met de SDK van Okta.

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 Description
handtekening Gevalideerd met behulp van ondertekeningssleutels die zijn gedetecteerd via de geconfigureerde jwt.issuer instantie (OpenID Connect-metagegevens/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)

Probleemoplossingsproces

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 Rollenclaim ontbreekt Uw IdP configureren om een roles claim op te nemen
403 Forbidden Verkeerde claimnaam DAB maakt gebruik van claimtype roles (vast, niet configureerbaar)

Belangrijk

DAB gebruikt momenteel het claimtype roles voor alle rolcontroles. Deze waarde is vastgelegd en kan niet worden gewijzigd in groups, permissionsof andere claimnamen. Configureer uw id-provider om rollen uit te zenden voor een claim met de naam roles.

Algemene formaten voor issuers

Provider Formaat van uitgever
Okta https://<domain>.okta.com of https://<domain>.okta.com/oauth2/default
Verificatie0 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