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

Podpora rozhraní Data API zahrnuje poskytovatele identity třetích stran prostřednictvím vlastní metody ověřování pomocí validace JSON Web Token (JWT). 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:

Diagram znázorňující vlastní tok ověřování JWT s zprostředkovatelem identity třetí strany

Fáze	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í.

Předpoklady

Účet u vašeho zprostředkovatele identity (Okta, Auth0 atd.)
Aplikace zaregistrovaná u vašeho zprostředkovatele identity
Nainstalovaný Data API builder CLI (průvodce instalací)
Existující dab-config.json s alespoň jednou entitou

Stručná referenční dokumentace

Setting	Hodnota
Poskytovatel	`Custom`
Požadováno pro ověření	`iss`, `aud`, `exp`platný podpis
Požadováno pro autorizaci	`roles` deklarace identity, která obsahuje vybranou roli
Hlavička tokenu	`Authorization: Bearer <token>`
Typ deklarace 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 vydavatele	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

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

Příklad Auth0

Přihlaste se k řídicímu panelu Auth0.
Přejděte na aplikace>rozhraní API.
Vytvořte nebo vyberte rozhraní API.
Poznamenejte si identifikátor (použijte ho jako cílovou skupinu).
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áš poskytovatel identity generuje role v jiném claimu (například groups nebo permissions), nakonfigurujte ho tak, aby také generoval claim roles. Uživatelé Auth0 by měli před pokračováním zkontrolovat známý konflikt mezer mezi názvy .

Krok 2: Konfigurace tvůrce rozhraní Data API

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

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

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

Bash
Příkazový řádek

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

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í

V konzole pro správu Okta přejděte dorozhraní API>.
Vyberte svůj autorizační server.
Přejděte na kartu Požadavky.
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

Auth0 vyžaduje, aby vlastní deklarace používaly názvy odolné vůči kolizím a s oborem názvů (například https://example.com/roles). Claimy bez jmenného prostoru, které kolidují s rezervovanými názvy, jsou z tokenu bez upozornění vyloučeny. Další informace najdete v dokumentaci Auth0 v tématu Vytvoření vlastních deklarací.

Tvůrce rozhraní Data API očekává přesný název deklarace roles, nikoli variantu s oborem názvů. To, zda Auth0 přijímá claim bez jmenného prostoru roles, závisí na konfiguraci vašeho tenanta.

Na řídicím panelu Auth0 přejděte doakcí>knihovny.
Vytvoření nové akce (trigger po přihlášení)

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);
  }
};

Nasaďte akci a přidejte ji do toku přihlášení.
Ověřte dekódovaný přístupový token na jwt.io a potvrďte, že je přítomen atribut roles.

Warning

Auth0 může v závislosti na nastavení tenanta bez upozornění odstranit claim bez oboru názvů roles. Pokud v tokenu chybí claim, zkontrolujte v řídicím panelu Auth0 Nastavení>Pokročilé, zda je vynucování oboru názvů povoleno. Tenanti, kteří vyžadují claimy s oborem názvů, jsou v současné době nekompatibilní s autorizací založenou na rolích v nástroji Data API builder pro vlastní role. Vestavěné role authenticated a anonymous stále fungují, protože nezávisí na atributu roles.

Návod

Podrobné pokyny ke konfiguraci deklarací identity JWT s oktou najdete v tématu Přizpůsobení tokenů vrácených z Okty.

Krok 5: Otestování konfigurace

Spusťte Tvůrce rozhraní API pro data:
```
dab start
```
Získejte token od zprostředkovatele identity. Použijte sadu SDK vašeho poskytovatele nebo nástroj, jako je Postman.
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.

Zavolejte rozhraní API:

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

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 nebo sady webových klíčů JSON (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)

Troubleshooting

Symptom	Možná příčina	Řešení
`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`	Nenalezl se žádný `roles` požadavek.	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ý).
`403 Forbidden`	Vlastní claim Auth0 je tiše ignorován	Auth0 může odstranit vlastní claimy bez jmenného prostoru. Ověřte na jwt.io, že claim `roles` je v dekódovaném tokenu přítomen. Viz Auth0: Přidání rolí pomocí akce

Důležité

Typ deklarace identity roles je při všech kontrolách rolí pevně zadaný a nelze jej změnit. Nakonfigurujte poskytovatele identity tak, aby odesílal atribut s přesným názvem roles. Uživatelé Auth0 by měli zkontrolovat konflikt mezer mezi názvy.

Běžné formáty emitentů

Poskytovatel	Formát vystavitele
Okta	`https://<domain>.okta.com` nebo `https://<domain>.okta.com/oauth2/default`
Auth0	`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": ["*"]
        }
      ]
    }
  }
}

Váš názor

Byla tato stránka užitečná?

Last updated on 2026-05-14

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

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

Předpoklady

Stručná referenční dokumentace

Krok 1: Konfigurace zprostředkovatele identity

Hodnoty ke shromažďování

Příklad Okta

Příklad Auth0

Krok 2: Konfigurace tvůrce rozhraní Data API

CLI

Výsledná konfigurace

Krok 3: Konfigurace oprávnění entity

CLI

Výsledná konfigurace

Krok 4: Konfigurujte role ve zprostředkovateli identity

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

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

Krok 5: Otestování konfigurace

Podrobnosti o ověření JWT

Troubleshooting

Běžné formáty emitentů

Příklad dokončení konfigurace

Konfigurace Okta

Konfigurace Auth0

Související obsah

Váš názor

Další materiály