Simulare un'API CRUD protetta con Microsoft Entra

Quando si creano app, spesso si interagisce con le API back-end. A volte, queste API non sono ancora disponibili o altri team li aggiornano per soddisfare i requisiti più recenti. Per evitare l'attesa, in genere si crea un'API fittizia che restituisce i dati necessari. Anche se questo approccio sblocca l'utente, richiede di dedicare tempo alla creazione di un'API che alla fine si sostituisce con quella reale. Diventa ancora più complicato, quando è necessario proteggere l'API con Microsoft Entra. Per evitare perdite di tempo, è possibile usare Dev Proxy per simulare un'API CRUD e velocizzare lo sviluppo.

CrudApiPluginUsando , è possibile simulare un'API CRUD (Create, Read, Update, Delete) con un archivio dati in memoria. Usando un file di configurazione semplice, è possibile definire gli URL supportati dall'API fittizia e i dati restituiti. Il plug-in supporta anche CORS per l'utilizzo tra domini da applicazioni lato client. Il plug-in supporta anche l'autenticazione di Microsoft Entra, in modo da poter proteggere l'API fittizia con Microsoft Entra e implementare lo stesso flusso di autenticazione per l'app come nell'ambiente di produzione.

Scenario

Si supponga di creare un'app che consenta agli utenti di gestire i clienti. Per ottenere i dati, è necessario chiamare l'endpoint /customers dell'API back-end. L'API è protetta con Microsoft Entra. Per evitare di attendere il completamento del lavoro del team back-end, si decide di usare Dev Proxy per simulare l'API e restituire i dati necessari.

Operazioni preliminari

Per iniziare , creare un'API CRUD simulata con i dati dei clienti. Dopo aver verificato che l'API funzioni, è possibile proteggerla con Microsoft Entra.

Esempio 1: Simulare un'API CRUD protetta con Microsoft Entra usando un singolo ambito

Nel primo esempio si protegge l'intera API con un singolo ambito. Indipendentemente dal fatto che gli utenti debbano ottenere informazioni sui clienti o aggiornarli, usano la stessa autorizzazione.

customers-api.json Nel file aggiungere informazioni su Entra.

{
  "$schema": "https://raw.githubusercontent.com/microsoft/dev-proxy/main/schemas/v0.19.0/crudapiplugin.schema.json",
  "baseUrl": "https://api.contoso.com/v1/customers",
  "dataFile": "customers-data.json",
  "auth": "entra",
  "entraAuthConfig": {
    "audience": "https://api.contoso.com",
    "issuer": "https://login.microsoftonline.com/contoso.com",
    "scopes": ["api://contoso.com/user_impersonation"]
  },
  "actions": [
    {
      "action": "getAll"
    },
    {
      "action": "getOne",
      "url": "/{customer-id}",
      "query": "$.[?(@.id == {customer-id})]"
    },
    {
      "action": "create"
    },
    {
      "action": "merge",
      "url": "/{customer-id}",
      "query": "$.[?(@.id == {customer-id})]"
    },
    {
      "action": "delete",
      "url": "/{customer-id}",
      "query": "$.[?(@.id == {customer-id})]"
    }
  ]
}

Impostando la auth proprietà entra su si specifica, che l'API è protetta con Microsoft Entra. entraAuthConfig Nella proprietà specificare i dettagli di configurazione. La audience proprietà specifica il gruppo di destinatari dell'API, la issuer proprietà specifica l'autorità di certificazione dei token e la scopes proprietà specifica gli ambiti necessari per accedere all'API. Poiché si definisce scopes a livello radice del file API, tutte le azioni richiedono lo stesso ambito.

Se si tenta di chiamare l'API senza un token con il gruppo di destinatari, l'autorità di certificazione e gli ambiti specificati, si ottiene una 401 Unauthorized risposta.

Nota

In questa fase, Dev Proxy non convalida il token. Controlla solo se il token è presente e ha il gruppo di destinatari, l'emittente e gli ambiti necessari. Questo è utile durante lo sviluppo iniziale, quando non si ha ancora una registrazione reale dell'app Microsoft Entra e non è possibile ottenere un token reale.

Esempio 2: Simulare un'API CRUD protetta con Microsoft Entra usando ambiti diversi per azioni diverse

In molti casi, diverse operazioni API richiedono autorizzazioni diverse. Ad esempio, ottenere informazioni sui clienti potrebbe richiedere un'autorizzazione diversa rispetto all'aggiornamento. In questo esempio si proteggono azioni API diverse con ambiti diversi.

Aggiornare il customers-api.json file come segue:

{
  "$schema": "https://raw.githubusercontent.com/microsoft/dev-proxy/main/schemas/v0.19.0/crudapiplugin.schema.json",
  "baseUrl": "https://api.contoso.com/v1/customers",
  "dataFile": "customers-data.json",
  "auth": "entra",
  "entraAuthConfig": {
    "audience": "https://api.contoso.com",
    "issuer": "https://login.microsoftonline.com/contoso.com"
  },
  "actions": [
    {
      "action": "getAll",
      "auth": "entra",
      "entraAuthConfig": {
        "scopes": ["api://contoso.com/customer.read"]
      }
    },
    {
      "action": "getOne",
      "url": "/{customer-id}",
      "query": "$.[?(@.id == {customer-id})]",
      "auth": "entra",
      "entraAuthConfig": {
        "scopes": ["api://contoso.com/customer.read"]
      }
    },
    {
      "action": "create",
      "auth": "entra",
      "entraAuthConfig": {
        "scopes": ["api://contoso.com/customer.write"]
      }
    },
    {
      "action": "merge",
      "url": "/{customer-id}",
      "query": "$.[?(@.id == {customer-id})]",
      "auth": "entra",
      "entraAuthConfig": {
        "scopes": ["api://contoso.com/customer.write"]
      }
    },
    {
      "action": "delete",
      "url": "/{customer-id}",
      "query": "$.[?(@.id == {customer-id})]",
      "auth": "entra",
      "entraAuthConfig": {
        "scopes": ["api://contoso.com/customer.write"]
      }
    }
  ]
}

Questa volta non si specifica a scopes livello radice del file API. È invece necessario specificarli per ogni azione. In questo modo, è possibile proteggere azioni diverse con ambiti diversi. Ad esempio, ottenere informazioni sui clienti richiede l'ambito, mentre l'aggiornamento api://contoso.com/customer.read dei clienti richiede l'ambito api://contoso.com/customer.write .

Convalidare i token

Dev Proxy consente di simulare un'API CRUD protetta con Microsoft Entra e verificare di usare un token valido. La convalida del token è utile quando si ha una registrazione dell'app in Microsoft Entra, ma il team sta ancora creando l'API. Consente di testare in modo più accurato l'app.

Se si vuole che Dev Proxy convaliderà il token di accesso, alla entraAuthConfig proprietà aggiungere la validateSigningKey proprietà e impostarla su true:

{
  "$schema": "https://raw.githubusercontent.com/microsoft/dev-proxy/main/schemas/v0.19.0/crudapiplugin.schema.json",
  "baseUrl": "https://api.contoso.com/v1/customers",
  "dataFile": "customers-data.json",
  "auth": "entra",
  "entraAuthConfig": {
    "audience": "https://api.contoso.com",
    "issuer": "https://login.microsoftonline.com/contoso.com",
    "scopes": ["api://contoso.com/user_impersonation"],
    "validateSigningKey": true
  },
  "actions": [
    {
      "action": "getAll"
    },
    {
      "action": "getOne",
      "url": "/{customer-id}",
      "query": "$.[?(@.id == {customer-id})]"
    },
    {
      "action": "create"
    },
    {
      "action": "merge",
      "url": "/{customer-id}",
      "query": "$.[?(@.id == {customer-id})]"
    },
    {
      "action": "delete",
      "url": "/{customer-id}",
      "query": "$.[?(@.id == {customer-id})]"
    }
  ]
}

Se si tenta di chiamare l'API con un token auto-creato, si ottiene una 401 Unauthorized risposta. Dev Proxy consente solo le richieste con un token valido rilasciato da Microsoft Entra.

Passaggio successivo

Altre informazioni su CrudApiPlugin.

Esempi

Vedere anche gli esempi correlati di Dev Proxy: