Microsoft Entra ID-verificatie configureren

Deze handleiding begeleidt u bij het configureren van Microsoft Entra ID-verificatie (voorheen Azure Active Directory) voor Data API Builder. Aan het einde verifieert uw client-app gebruikers via Entra, verkrijgt tokens voor Data API Builder en KAN DAB beheerde identiteit gebruiken om verbinding te maken met Azure SQL.

Data API Builder verifieert binnenkomende aanvragen met JWT Bearer-validatie (EntraID/AzureAD/Custom) of door het platform geleverde identiteitsheaders ().AppService Gebruik de Simulator provider voor het testen van lokale ontwikkeling en machtigingen.

Gidsen voor authenticatieprovider

Kies een handleiding op basis van uw id-provider:

Authenticatiestroom

In het volgende diagram ziet u de volledige verificatiestroom bij het gebruik van Microsoft Entra-id met Data API Builder:

De stroom heeft drie verschillende fasen:

Vereiste voorwaarden

• Een Azure-abonnement met Microsoft Entra ID-tenant
• Data API Builder CLI geïnstalleerd (installatiehandleiding)
• Een bestaande dab-config.json met ten minste één entiteit
• (Optioneel) Scenario's voor beheerde identiteiten in Azure SQL Database

Snelzoekgids

Stap 1: Een toepassing registreren in Microsoft Entra-id

Maak een app-registratie die uw Data API Builder-API vertegenwoordigt. Client-apps vragen tokens aan met een doelgroep die overeenkomt met deze registratie.

1. Meld u aan bij het Microsoft Entra-beheercentrum.

2. Navigeer naar Identiteit>Toepassingen>App-registraties.

3. Selecteer Nieuwe registratie.

4. Voer een naam in (bijvoorbeeld Data API Builder API).

5. Selecteer de juiste ondersteunde accounttypen voor uw scenario:

   • Eén tenant: alleen gebruikers in uw organisatie
   • Multitenant: gebruikers in elke Microsoft Entra-directory

6. Laat de omleidings-URI leeg (deze registratie is voor de API, niet voor de client).

7. Selecteer Registreren.

8. Noteer deze waarden op de overzichtspagina van de app:

   Waarde	Waar vind ik het?	Gebruikt voor
   Applicatie (cliënt) ID	Overzichtspagina	De doelgroep-URI bouwen
   Directory (huurder) ID	Overzichtspagina	De URL van de uitgever bouwen

Configureer de toepassings-ID URI

1. Ga in de app-registratie naar Een API beschikbaar maken.

2. Selecteer Toevoegen naast de URI van de toepassings-id.

3. Accepteer de standaardwaarde (api://<app-id>) of voer een aangepaste URI in.

4. Selecteer Opslaan.

App-rollen toevoegen (optioneel)

Als u aangepaste rollen wilt gebruiken buiten Anonymous en Authenticated:

1. Ga naar App-rollen.

2. Selecteer App-rol aanmaken.

3. Binnenkomen:

   • Weergavenaam: Reader
   • Toegestane lidtypen: gebruikers/groepen of beide
   • Waarde: reader (deze waarde wordt weergegeven in de claim van roles het token)
   • Beschrijving: Read-only access to data

4. Selecteer de optie Toepassen.

5. Herhaal dit voor extra rollen (bijvoorbeeld writer, admin).

Stap 2: Data API Builder configureren

Configureer DAB om tokens te valideren die zijn uitgegeven door uw Entra-tenant voor uw API-doelgroep.

CLI (Command Line Interface)

# Set the authentication provider
dab configure \
  --runtime.host.authentication.provider EntraID

# Set the expected audience (Application ID URI)
dab configure \
  --runtime.host.authentication.jwt.audience "api://<your-app-id>"

# Set the expected issuer (your tenant)
dab configure \
  --runtime.host.authentication.jwt.issuer "https://login.microsoftonline.com/<your-tenant-id>/v2.0"

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

REM Set the expected audience (Application ID URI)
dab configure ^
  --runtime.host.authentication.jwt.audience "api://<your-app-id>"

REM Set the expected issuer (your tenant)
dab configure ^
  --runtime.host.authentication.jwt.issuer "https://login.microsoftonline.com/<your-tenant-id>/v2.0"

Resulterende configuratie

{
  "runtime": {
    "host": {
      "authentication": {
        "provider": "EntraID",
        "jwt": {
          "audience": "api://<your-app-id>",
          "issuer": "https://login.microsoftonline.com/<your-tenant-id>/v2.0"
        }
      }
    }
  }
}

Stap 3: Entiteitsmachtigingen configureren

Definieer welke rollen toegang hebben tot elke entiteit. Aanvragen worden geëvalueerd op basis van de rol die is bepaald op basis van het token.

Toegang verlenen aan geverifieerde gebruikers

dab update Book \
  --permissions "Authenticated:read"

dab update Book ^
  --permissions "Authenticated:read"

Toegang verlenen tot een aangepaste rol

dab update Book \
  --permissions "reader:read" \
  --permissions "writer:create,read,update"

dab update Book ^
  --permissions "reader:read" ^
  --permissions "writer:create,read,update"

Resulterende configuratie

{
  "entities": {
    "Book": {
      "source": "dbo.Books",
      "permissions": [
        {
          "role": "Authenticated",
          "actions": ["read"]
        },
        {
          "role": "reader",
          "actions": ["read"]
        },
        {
          "role": "writer",
          "actions": ["create", "read", "update"]
        }
      ]
    }
  }
}

Stap 4: Databaseverbinding configureren

Data API Builder maakt verbinding met de database met behulp van een eigen identiteit, gescheiden van de geverifieerde gebruiker. Gebruik beheerde identiteit voor productiescenario's met Azure SQL.

Optie A: Beheerde identiteit (aanbevolen voor Azure)

Door het systeem toegewezen beheerde identiteit

{
  "data-source": {
    "database-type": "mssql",
    "connection-string": "Server=tcp:<server>.database.windows.net,1433;Initial Catalog=<database>;Authentication=Active Directory Managed Identity;Encrypt=True;"
  }
}

Door de gebruiker toegewezen beheerde identiteit

{
  "data-source": {
    "database-type": "mssql",
    "connection-string": "Server=tcp:<server>.database.windows.net,1433;Initial Catalog=<database>;Authentication=Active Directory Managed Identity;User Id=<uami-client-id>;Encrypt=True;"
  }
}

Optie B: SQL-verificatie (ontwikkeling)

{
  "data-source": {
    "database-type": "mssql",
    "connection-string": "@env('SQL_CONNECTION_STRING')"
  }
}

Optie C: Lokale ontwikkeling met az login

Gebruik uw Azure CLI-referenties voor lokale ontwikkeling in Azure SQL:

{
  "data-source": {
    "database-type": "mssql",
    "connection-string": "Server=tcp:<server>.database.windows.net,1433;Initial Catalog=<database>;Authentication=Active Directory Default;Encrypt=True;"
  }
}

Meld u aan voordat u DAB start:

az login

Stap 5: De configuratie testen

1. Start Data API Builder:

   dab start
   

2. Een token verkrijgen voor uw API. Gebruik de Microsoft Authentication Library (MSAL) of een hulpprogramma zoals jwt.ms voor testen.

3. Roep de API aan met het token:

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

4. 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: reader"
   

Gedrag van rolselectie

Data API Builder bepaalt de rol van de aanvraag met behulp van deze logica:

Probleemoplossingsproces

Volledig configuratievoorbeeld

{
  "$schema": "https://github.com/Azure/data-api-builder/releases/latest/download/dab.draft.schema.json",
  "data-source": {
    "database-type": "mssql",
    "connection-string": "Server=tcp:myserver.database.windows.net,1433;Initial Catalog=mydb;Authentication=Active Directory Managed Identity;Encrypt=True;"
  },
  "runtime": {
    "host": {
      "authentication": {
        "provider": "EntraID",
        "jwt": {
          "audience": "api://dab-api-12345678",
          "issuer": "https://login.microsoftonline.com/contoso.onmicrosoft.com/v2.0"
        }
      }
    }
  },
  "entities": {
    "Book": {
      "source": "dbo.Books",
      "permissions": [
        {
          "role": "Authenticated",
          "actions": ["read"]
        },
        {
          "role": "librarian",
          "actions": ["create", "read", "update", "delete"]
        }
      ]
    }
  }
}

Verwante inhoud

• Autorisatie en rollen
• Simulatorverificatie configureren voor testen
• App Service-verificatie configureren
• Handleiding voor runtime-configuratie