Sdílet prostřednictvím

Konfigurace vlastního ověřování JWT (Okta, Auth0)

Tvůrce rozhraní DATA API podporuje zprostředkovatele identity třetích stran prostřednictvím vlastního zprostředkovatele ověřování. Tento přístup použijte, když vaše organizace používá zprostředkovatele identity kompatibilní s protokolem Okta, Auth0 nebo jiný zprostředkovatel identity kompatibilní s OAuth 2.0/OpenID Connect.

Průběh ověřování

Pomocí vlastního zprostředkovatele identity vaše klientská aplikace zpracovává ověřování uživatelů a pak odešle přístupový token tvůrci rozhraní Data API:

Obrázek vlastního toku ověřování JWT s zprostředkovatelem identity třetí strany

Phase Co se stane
Ověřování uživatelů Uživatel se přihlásí prostřednictvím zprostředkovatele identity (Okta, Auth0 atd.)
Získání tokenu Klientská aplikace obdrží přístupový token od zprostředkovatele identity.
Volání rozhraní API Klient odešle token do DAB v Authorization hlavičce.
Ověření DAB ověří JWT (vystavitel, cílová skupina, podpis).
Authorization DAB extrahuje role a vyhodnocuje oprávnění.

Požadavky

  • Účet u vašeho zprostředkovatele identity (Okta, Auth0 atd.)
  • Aplikace zaregistrovaná u vašeho zprostředkovatele identity
  • Nainstalované rozhraní příkazového řádku Data API Builder (průvodce instalací)
  • Existující dab-config.json s alespoň jednou entitou

Stručná referenční dokumentace

Setting Hodnota
Provider Custom
Požadováno pro ověření iss, aud, expplatný podpis
Požadováno pro autorizaci roles nárok obsahující vybranou roli
Hlavička tokenu Authorization: Bearer <token>
Typ nároku identity role roles (opraveno, ne konfigurovatelné)
Nadpis výběru role X-MS-API-ROLE

Krok 1: Konfigurace zprostředkovatele identity

Přesný postup závisí na vašem poskytovateli. Tady jsou hodnoty klíče, které potřebujete:

Hodnoty ke shromažďování

Hodnota Kde to najít Používá se pro
Adresa URL vystavitele Dokumentace poskytovatele nebo koncový bod metadat OAuth DAB jwt.issuer (používá se jako autorita JWT)
Obecenstvo ID klienta vaší aplikace nebo vlastní identifikátor rozhraní API DAB jwt.audience

Poznámka:

DAB používá nakonfigurovanou jwt.issuerautoritu JWT. Podpisové klíče se automaticky zjistí prostřednictvím standardních metadat OpenID Connect (obvykle <issuer>/.well-known/openid-configuration).

Příklad Okta

  1. Přihlaste se ke konzole pro správu Okta.
  2. Přejděte do aplikací>aplikací.
  3. Vytvořte nebo vyberte aplikaci.
  4. Poznamenejte si ID klienta (použijte jako cílovou skupinu).
  5. Váš vystavitel je obvykle https://<your-domain>.okta.com.

Příklad Auth0

  1. Přihlaste se k řídicímu panelu Auth0.
  2. Přejděte na aplikace>rozhraní API.
  3. Vytvořte nebo vyberte rozhraní API.
  4. Poznamenejte si identifikátor (použijte ho jako cílovou skupinu).
  5. Váš vystavitel je https://<your-tenant>.auth0.com/.

Důležité

Tvůrce rozhraní Data API používá pevný typ nároku roles pro autorizaci založenou na rolích. Tuto hodnotu nelze nakonfigurovat. Pokud váš zprostředkovatel identity generuje role v jiné deklaraci identity (například groups nebo permissions), musíte poskytovatele nakonfigurovat tak, aby také generoval deklaraci identity roles, nebo pomocí akce po přihlášení zkopírujte hodnoty do deklarace identity roles.

Krok 2: Konfigurace tvůrce rozhraní Data API

Nastavte zprostředkovatele ověřování na Custom a nakonfigurujte nastavení JWT:

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

Výsledná konfigurace

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

Krok 3: Konfigurace oprávnění entity

Definujte oprávnění pro role, které váš zprostředkovatel identity přiřadí:

CLI

# Allow authenticated users to read
dab update Book \
  --permissions "authenticated:read"

# Allow users with 'admin' role full access
dab update Book \
  --permissions "admin:*"

Výsledná konfigurace

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

Krok 4: Konfigurujte role ve zprostředkovateli identity

DAB očekává role v roles nároku. Nakonfigurujte zprostředkovatele identity tak, aby zahrnoval tento claim.

Okta: Přidání skupin jako rolí

  1. V konzole pro správu Okta přejděte dorozhraní API>.
  2. Vyberte svůj autorizační server.
  3. Přejděte na kartu Požadavky.
  4. Přidat nárok:
    • Název: roles
    • Zahrnout do typu tokenu: Přístupový token
    • Typ hodnoty: Skupiny
    • Filtr: Vyberte skupiny, které chcete zahrnout.

Auth0: Přidání rolí pomocí akce

  1. Na řídicím panelu Auth0 přejděte doakcí>knihovny.
  2. Vytvoření nové akce (trigger po přihlášení)
  3. Přidejte kód pro zahrnutí rolí:
exports.onExecutePostLogin = async (event, api) => {
  const roles = event.authorization?.roles || [];
  if (roles.length > 0) {
    api.accessToken.setCustomClaim('roles', roles);
  }
};
  1. Nasaďte akci a přidejte ji do toku přihlášení.

Návod

Podrobné pokyny ke konfiguraci deklarací identity JWT s oktou najdete v tématu Implementace pokročilých deklarací identity JWT pomocí sady OKTA SDK.

Krok 5: Otestování konfigurace

  1. Spusťte Tvůrce rozhraní API pro data:

    dab start

  2. Získejte token od zprostředkovatele identity. Použijte sadu SDK vašeho poskytovatele nebo nástroj, jako je Postman.

  3. Zkontrolujte token na jwt.io a ověřte:

    • Deklarace aud identity odpovídá nakonfigurované cílové skupině.
    • Tvrzení iss odpovídá vašemu nakonfigurovanému vystaviteli.
    • Nárok roles obsahuje očekávané hodnoty.

  4. Zavolejte rozhraní API:

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

  5. Pokud chcete použít vlastní roli, zahrňte hlavičku X-MS-API-ROLE :

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

Podrobnosti o ověření JWT

Tvůrce rozhraní Data API ověřuje tyto aspekty JWT:

Zkontrolujte Description
Podpis Ověřeno pomocí podpisových klíčů zjištěných prostřednictvím nakonfigurované jwt.issuer autority (metadata OpenID Connect / JWKS)
Emitent Musí přesně odpovídat jwt.issuer konfiguraci.
Obecenstvo Musí přesně odpovídat jwt.audience konfiguraci.
vypršení platnosti Platnost tokenu nesmí vypršet (exp nárok)
Ne dříve než Token musí být platný (nbf deklarace identity, pokud existuje)

Řešení problémů

Příznaky Možná příčina Solution
401 Unauthorized Neshoda vydavatelů Zkontrolujte, jestli iss deklarace identity přesně odpovídá (včetně koncového lomítka).
401 Unauthorized Neshoda cílové skupiny Zkontrolujte, jestli aud položka odpovídá vaší nakonfigurované hodnotě.
401 Unauthorized Platnost tokenu vypršela Získání nového tokenu
401 Unauthorized Nedostupná metadata Ujistěte se, že DAB může dosáhnout <issuer>/.well-known/openid-configuration
403 Forbidden Role není v tokenu Přidejte roli do konfigurace poskytovatele identity
403 Forbidden Chybí deklarace rolí Konfigurujte IdP tak, aby zahrnovalo roles deklaraci
403 Forbidden Nesprávný název nároku DAB používá typ požadavku roles (pevný, ne konfigurovatelný).

Důležité

DAB v současné době používá typ roles pro všechny kontroly rolí. Tato hodnota je pevně zakódovaná a nelze ji změnit na groups, permissionsani na jiné názvy deklarací identity. Nakonfigurujte zprostředkovatele identity tak, aby vygeneroval role v deklaraci identity s názvem roles.

Běžné formáty emitentů

Provider Formát vystavitele
Okta https://<domain>.okta.com nebo https://<domain>.okta.com/oauth2/default
Ověřování 0 https://<tenant>.auth0.com/ (všimněte si koncového lomítka)
Azure AD B2C https://<tenant>.b2clogin.com/<tenant-id>/v2.0/
Keycloak https://<host>/realms/<realm>

Příklad dokončení konfigurace

Konfigurace Okta

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

Konfigurace Auth0

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

Související obsah

  • Last updated on