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:

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

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

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

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

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

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

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

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

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

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:

Probleemoplossingsproces

Algemene formaten voor issuers

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

• Autorisatie en rollen
• Microsoft Entra ID-verificatie configureren
• Simulatorverificatie configureren voor testen
• Handleiding voor runtime-configuratie