Konfigurera anpassad JWT-autentisering (Okta, Auth0)

Data API Builder stöder identitetsleverantörer från tredje part genom verifiering med en anpassad autentiseringsleverantör och JSON-webbtoken (JWT). Använd den här metoden när din organisation använder Okta, Auth0 eller någon annan OAuth 2.0/OpenID Connect-kompatibel identitetsprovider.

Autentiseringsflöde

Med en anpassad identitetsprovider hanterar klientappen användarautentisering och skickar sedan åtkomsttoken till Data API Builder:

Förutsättningar

• Ett konto med din identitetsprovider (Okta, Auth0 osv.)
• En applikation registrerad i din identitetsleverantör
• Cli för data-API-byggare installerad (installationsguide)
• En befintlig dab-config.json med minst en entitet

Snabbreferens

Steg 1: Konfigurera din identitetsprovider

De exakta stegen beror på leverantören. Här är de nyckelvärden som du behöver:

Värden att samla in

Okta exempel

1. Logga in på okta-administratörskonsolen.
2. Gå till Program>Program.
3. Skapa eller välj ett program.
4. Observera klient-ID :t (används som målgrupp).
5. Utfärdaren är vanligtvis https://<your-domain>.okta.com.

Auth0-exempel

1. Logga in på instrumentpanelen Auth0.
2. Gå till Program>API:er.
3. Skapa eller välj ett API.
4. Observera identifieraren (använd som målgrupp).
5. Utfärdaren är https://<your-tenant>.auth0.com/.

Steg 2: Konfigurera data-API-byggare

Ange autentiseringsprovidern till Custom och konfigurera JWT-inställningarna:

CLI

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

Resulterande konfiguration

{
  "runtime": {
    "host": {
      "authentication": {
        "provider": "Custom",
        "jwt": {
          "audience": "<your-api-identifier>",
          "issuer": "https://<your-issuer>/"
        }
      }
    }
  }
}

Steg 3: Konfigurera entitetsbehörigheter

Definiera behörigheter för de roller som identitetsprovidern tilldelar:

CLI

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

Resulterande konfiguration

{
  "entities": {
    "Book": {
      "source": "dbo.Books",
      "permissions": [
        {
          "role": "authenticated",
          "actions": ["read"]
        },
        {
          "role": "admin",
          "actions": ["*"]
        }
      ]
    }
  }
}

Steg 4: Konfigurera roller i din identitetsprovider

DAB förväntar sig roller i ett roles anspråk. Konfigurera identitetsprovidern så att den inkluderar det här anspråket.

Okta: Lägga till grupper som roller

1. I okta-administratörskonsolen går du till Säkerhets-API>.
2. Välj din auktoriseringsserver.
3. Gå till fliken Anspråk .
4. Lägg till ett anspråk:
   • Namn: roles
   • Inkludera i tokentyp: Åtkomsttoken
   • Värdetyp: Grupper
   • Filter: Välj de grupper som ska inkluderas

Auth0: Lägga till roller med en åtgärd

Auth0 kräver anpassade anspråk för att använda kollisionsresistenta namnområdesnamn (till exempel https://example.com/roles). Anspråk utan namnområde som krockar med reserverade namn utesluts utan meddelande från tokenen. Mer information finns i Skapa anpassade anspråk i Auth0-dokumentationen.

Data API Builder förväntar sig det exakta anspråksnamnet roles, inte en namnområdesvariant. Om Auth0 accepterar ett anspråk som inte är namnområde roles beror på klientkonfigurationen.

1. I instrumentpanelen Auth0 går du till Åtgärdsbibliotek>.

2. Skapa en ny åtgärd (utlösare efter inloggning).

3. Lägg till kod för att inkludera roller:

   exports.onExecutePostLogin = async (event, api) => {
     const roles = event.authorization?.roles || [];
     if (roles.length > 0) {
       api.accessToken.setCustomClaim('roles', roles);
     }
   };
   

4. Distribuera åtgärden och lägg till den i ditt inloggningsflöde.

5. Verifiera den avkodade åtkomsttokenpå jwt.io och bekräfta att anspråket roles finns.

Steg 5: Testa konfigurationen

1. Starta data-API-byggare:

   dab start
   

2. Hämta en token från din identitetsprovider. Använd leverantörens SDK eller ett verktyg som Postman.

3. Kontrollera token vid jwt.io för att verifiera:

   • Anspråket aud matchar din konfigurerade målgrupp
   • Anspråket iss matchar din konfigurerade utfärdare
   • Anspråket roles innehåller de förväntade värdena

4. Anropa API:et:

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

5. Om du vill använda en anpassad roll inkluderar du X-MS-API-ROLE rubriken:

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

JWT-verifieringsinformation

Data API Builder validerar dessa aspekter av JWT:

Felsökning

Vanliga format för utfärdare

Komplett konfigurationsexempel

Okta-konfiguration

{
  "$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-konfiguration

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

Relaterat innehåll

• Översikt över auktorisering
• Konfigurera Microsoft Entra ID-autentisering
• Konfigurera simulatorautentisering för testning
• Referens för programkörningskonfiguration