Configuración de la autenticación de Microsoft Entra ID

Esta guía le guía a través de la configuración de la autenticación de Microsoft Entra ID (anteriormente Azure Active Directory) para data API Builder. Al final, la aplicación cliente autentica a los usuarios a través de Entra, adquiere tokens para data API Builder y DAB puede usar la identidad administrada para conectarse a Azure SQL.

Data API Builder autentica las solicitudes entrantes mediante la validación de portadores de JSON Web Token (JWT) () o encabezados de identidad proporcionados por la plataforma (). Para el desarrollo local y las pruebas de permisos, utilice el proveedor .

Ilustración de cómo los clientes se autentican en Data API Builder mediante tokens JWT.

Guides del proveedor de autenticación

Elija una guía basada en su proveedor de identidad.

Flujo de autenticación

El flujo tiene tres fases distintas:

Prerrequisitos

• Una suscripción de Azure con un inquilino de Microsoft Entra ID
• CLI de Data API Builder instalada (guía de instalación)
• Un existente con al menos una entidad
• (Opcional) Azure SQL Database para escenarios de identidad administrada

Referencia rápida

Paso 1: Registrar una aplicación en Microsoft Entra ID

Cree un registro de aplicación que represente la API de Data API Builder. Las aplicaciones cliente solicitan tokens con una audiencia que coincida con este registro.

1. Inicie sesión en el centro de administración Microsoft Entra.

2. Vaya a Identidad>Aplicaciones>Registro de aplicaciones.

3. Seleccione Nuevo registro.

4. Escriba un nombre (por ejemplo, ).

5. Seleccione los tipos de cuenta admitidos adecuados para su escenario:

   • Inquilino único: solo los usuarios de la organización
   • Multitenant: Usuarios de cualquier directorio de Microsoft Entra

6. Deje el URI de redirección en blanco (este registro es para la API, no para el cliente).

7. Seleccione Registrar.

8. En la página Información general de la aplicación, registre estos valores:

   Importancia	Dónde encontrarla	Se utiliza para
   Id. de la aplicación (cliente)	Página de información general	Creación del URI de audiencia
   Id. de directorio (inquilino)	Página de información general	Creación de la dirección URL del emisor

Configurar el URI de ID de aplicación

1. En el registro de la aplicación, vaya a Exponer una API.

2. Seleccione Agregar junto a URI de id. de aplicación.

3. Acepte el valor predeterminado () o escriba un URI personalizado.

4. Haga clic en Guardar.

Agregar un ámbito

Se requiere un ámbito para que las aplicaciones cliente (incluido Azure CLI) puedan solicitar tokens de acceso delegados para su API.

1. En el registro de la aplicación, vaya a Exponer una API.

2. En Ámbitos definidos con esta API, seleccione Agregar un ámbito.

3. Especifique:

   • nombre Scope: Endpoint.Access
   • ¿Quién puede dar el consentimiento? : Administradores y usuarios
   • Nombre para mostrar del consentimiento del administrador:
   • Descripción del consentimiento del administrador:
   • Nombre para mostrar del consentimiento del usuario:
   • Descripción del consentimiento del usuario:
   • Estado: Habilitado

4. Selecciona la opción Agregar un ámbito.

Agregar roles de aplicación (opcional)

Si desea usar roles personalizados más allá de y :

1. Vaya a Roles de aplicación.

2. Seleccione Crear rol de aplicación.

3. Especifique:

   • Nombre para mostrar:
   • Tipos de miembros permitidos: Usuarios/grupos o Ambos
   • Valor: (este valor aparece en la declaración del token)
   • Description: Read-only access to data

4. Seleccione Aplicar.

5. Repita para más roles (por ejemplo, , ).

Establece la versión del token de manifiesto

De forma predeterminada, el manifiesto de registro de aplicaciones establece el atributo en un valor específico, lo que genera tokens v1.0. Los tokens V1 usan un formato de emisor diferente (https://sts.windows.net/<tenant-id>/) que el emisor v2.0 configurado en DAB, lo que hace que se produzca un error en la validación del token.

1. En el registro de la aplicación, vaya a Manifiesto.

2. Busque y cambie el valor a .

3. Haga clic en Guardar.

Asignación de usuarios a roles de aplicación

La creación de roles de aplicación no las concede automáticamente a los usuarios. Debe asignar usuarios o grupos a través de la aplicación empresarial.

1. En el centro de administración Microsoft Entra, vaya a IdentityApplicationsAplicaciones empresariales.

2. Busque y seleccione la aplicación (por ejemplo, ). Una aplicación empresarial se creó automáticamente cuando registró la aplicación.

3. Vaya a Usuarios y grupos.

4. Seleccione Agregar usuario o grupo.

5. En Usuarios, seleccione la cuenta de usuario que desea asignar y seleccione Seleccionar.

6. En Seleccionar un rol, elija el rol que se va a asignar (por ejemplo, ). Si el rol no aparece, espere unos minutos a que se complete la replicación de Microsoft Entra.

7. Seleccione Asignar.

8. Repita para cada rol que quiera asignar.

Paso 2: Configuración de Data API Builder

Configure DAB para validar los tokens emitidos por el inquilino de Entra para la audiencia de API.

Interfaz de línea de comandos (CLI)

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

Configuración resultante

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

Paso 3: Configuración de permisos de entidad

Defina qué roles pueden acceder a cada entidad. Las solicitudes se evalúan en función del rol determinado por el token.

Conceder acceso a usuarios autenticados

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

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

Conceder acceso a rol personalizado

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

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

Configuración resultante

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

Paso 4: Configurar la conexión de base de datos

Data API Builder se conecta a la base de datos mediante su propia identidad, independiente del usuario autenticado. Para escenarios de producción con Azure SQL, use la identidad administrada.

Opción A: Identidad administrada (recomendada para Azure)

Identidad administrada asignada por el sistema

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

Identidad administrada asignada por el usuario

{
  "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;"
  }
}

Opción B: Autenticación de SQL (desarrollo)

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

Opción C: Desarrollo local con

Para el desarrollo local con Azure SQL, use las credenciales de Azure CLI:

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

Antes de iniciar DAB, iniciar sesión:

az login

Paso 5: Probar la configuración

Autorización de Azure CLI como aplicación cliente

Para que Azure CLI pueda adquirir tokens para la API, debe agregarlo como una aplicación cliente autorizada.

1. En el registro de la aplicación, vaya a Exponer una API.

2. En Aplicaciones cliente autorizadas, seleccione Agregar una aplicación cliente.

3. Escriba el identificador de cliente Azure CLI: 00001111-aaaa-2222-bbbb-3333cccc4444.

4. Seleccione el ámbito api://<app-id>/Endpoint.Access.

5. Seleccione Agregar una aplicación.

Adquisición de un token con Azure CLI

Inicie sesión utilizando Azure CLI y establezca el tenant donde existe el registro de aplicación.

az login
az account set --tenant <your-tenant-id>

Solicite un token limitado a su API.

az account get-access-token --scope api://<your-app-id>/Endpoint.Access --query "accessToken" -o tsv

Puede inspeccionar el token en jwt.ms para comprobar las notificaciones , y .

Iniciar DAB y enviar una solicitud

1. Inicie el generador de Data API:

   dab start
   

2. Llame a la API con el token:

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

3. Para usar un rol personalizado, incluya el encabezado :

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

Comportamiento de selección de roles

Data API Builder determina el rol de la solicitud mediante esta lógica:

Solución de problemas

Ejemplo de configuración completa

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

Contenido relacionado

• Autorización y roles
• Configuración de la autenticación del simulador para pruebas
• Configurar la autenticación de App Service
• Referencia de configuración en tiempo de ejecución