Egyéni JWT-hitelesítés konfigurálása (Okta, Hitelesítés0)

A Data API Builder az egyéni hitelesítésszolgáltatón keresztül támogatja a külső identitásszolgáltatókat JSON Web Token (JWT) érvényesítés használatával. Ezt a módszert akkor használja a szervezet, ha Okta, Auth0 vagy más OAuth 2.0/OpenID Connect-kompatibilis identitásszolgáltatót használ.

Hitelesítési folyamat

Egyéni identitásszolgáltató esetén az ügyfélalkalmazás kezeli a felhasználói hitelesítést, majd elküldi a hozzáférési jogkivonatot a Data API Buildernek:

Ábra az egyéni JWT-hitelesítési folyamatról egy külső identitásszolgáltatóval.

Phase	Mi történik?
Felhasználói hitelesítés	A felhasználó az identitásszolgáltatón keresztül jelentkezik be (Okta, Hitelesítés stb.)
Token beszerzése	Az ügyfélalkalmazás hozzáférési tokent kap az identitásszolgáltatótól
API-hívás	Az ügyfél elküldi a jogkivonatot a DAB-nak a `Authorization` fejlécben
Validation	A DAB ellenőrzi a JWT-t (kiállító, célközönség, aláírás)
Authorization	A DAB kinyeri a szerepköröket és kiértékeli az engedélyeket

Előfeltételek

Fiók azonosításszolgáltatóval (Okta, Auth0 stb.)
Az identitásszolgáltatóban regisztrált alkalmazás
Telepített Data API Builder CLI (telepítési útmutató)
Legalább egy entitással rendelkező meglévő dab-config.json

Rövid összefoglalás

Setting	Érték
Szolgáltató	`Custom`
Az ellenőrzéshez szükséges	`iss`, `aud`, `exp`érvényes aláírás
Engedélyezéshez szükséges	`roles` a kijelölt szerepkört tartalmazó jogcím
Jogkivonat fejléce	`Authorization: Bearer <token>`
Szerepkör igény típusa	`roles` (fix, nem konfigurálható)
Szerepkör-kijelölés fejléce	`X-MS-API-ROLE`

1. lépés: Az identitásszolgáltató konfigurálása

A pontos lépések a szolgáltatótól függenek. A legfontosabb értékek a következők:

Gyűjtendő értékek

Érték	Hol találja meg?	A következőhöz használatos:
Kiállító URL-címe	A szolgáltató dokumentációja vagy az OAuth metaadat-végpontja	DAB `jwt.issuer` (JWT-szolgáltatóként használatos)
Hallgatóság	Az alkalmazás ügyfélazonosítója vagy egyéni API-azonosítója	DAB `jwt.audience`

Megjegyzés:

A DAB a konfigurált jwt.issuerJWT-szolgáltatót használja. Az aláírási kulcsokat a rendszer automatikusan észleli a standard OpenID Connect-metaadatokon keresztül (általában <issuer>/.well-known/openid-configuration).

Okta-példa

Jelentkezzen be az Okta felügyeleti konzolra.
Navigáljon az Alkalmazásalkalmazások>elemre.
Hozzon létre vagy válasszon ki egy alkalmazást.
Jegyezze fel az ügyfélazonosítót (célközönségként használva).
A kiállító általában https://<your-domain>.okta.com.

Auth0 példa

Jelentkezzen be az Auth0 irányítópultra.
Navigáljon az Alkalmazások>API-khoz.
Hozzon létre vagy válasszon ki egy API-t.
Jegyezze fel az azonosítót (célközönségként használva).
Az Ön kibocsátója a https://<your-tenant>.auth0.com/.

Fontos

A Data API Builder rögzített jogcímtípust roles használ a szerepköralapú engedélyezéshez. Ez az érték nem konfigurálható. Ha az identitásszolgáltató szerepköröket bocsát ki egy másik jogcímben (például groups vagy permissions), konfigurálja azt úgy, hogy jogcímet roles is kibocsátson. Az auth0-felhasználóknak a folytatás előtt érdemes áttekinteniük az ismert névszámítási ütközést .

2. lépés: A Data API Builder konfigurálása

Állítsa be a hitelesítésszolgáltatót Custom, és konfigurálja a JWT-beállításokat.

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

Az eredményként kapott konfiguráció

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

3. lépés: Entitásengedélyek konfigurálása

Adja meg az identitásszolgáltató által hozzárendelt szerepkörök engedélyeit:

parancssori felület

Bash
Parancssor

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

Az eredményként kapott konfiguráció

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

4. lépés: Szerepkörök konfigurálása az identitásszolgáltatóban

A DAB szerepköröket vár egy roles jogcímben. Konfigurálja az identitásszolgáltatót úgy, hogy belefoglalja ezt az állítást.

Okta: Csoportok hozzáadása szerepkörként

Az Okta felügyeleti konzolon nyissa meg a Security>API-t.
Válassza ki az engedélyezési kiszolgálót.
Lépjen a Jogcímek lapra.
Jogcím hozzáadása:
- Név: roles
- Belefoglalás a tokentípusba: Hozzáférési jogkivonat
- Érték típusa: Csoportok
- Szűrő: Jelölje ki a felvenni kívánt csoportokat

Hitelesítés: Szerepkörök hozzáadása művelettel

Az Auth0 megköveteli, hogy az egyéni jogcímek ütközésálló, névterű neveket (például https://example.com/roles) használjanak. A fenntartott nevekkel ütköző, névtér nélküli jogcímállítások csendben kizárásra kerülnek a tokenből. További információ: Egyéni jogcímek létrehozása az Auth0 dokumentációjában.

A Data API Builder a jogcím pontos nevét rolesvárja, nem pedig névtérben megadott változatot. Az, hogy az Auth0 elfogad-e egy névtér nélküli roles jogcímet, a bérlő konfigurációjától függ.

Az Auth0 irányítópulton nyissa meg a Műveletek>tárat.
Hozzon létre egy új műveletet (bejelentkezés utáni eseményindító).

Kód hozzáadása szerepkörök hozzáadásához:

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

Telepítse a műveletet, és adja hozzá a bejelentkezési folyamathoz.
Ellenőrizze a dekódolt hozzáférési jogkivonatot jwt.io , és ellenőrizze, hogy a roles jogcím létezik-e.

Warning

Az Auth0 a bérlő beállításaitól függően észrevétlenül elvetheti a nem névtérhez tartozó roles claimet. Ha az attribútum hiányzik a tokenből, ellenőrizze az Auth0 Dashboardon a Beállítások>Speciális résznél a névtér kikényszerítésének beállítását. A névteres jogcímeket igénylő bérlők jelenleg nem kompatibilisek a Data API Builder egyéni szerepkörök szerepköralapú engedélyezésével. A beépített authenticated és anonymous szerepkörök továbbra is működnek, mert nem függenek a(z) roles jogcímtől.

Jótanács

A JWT-jogcímek Okta-val való konfigurálásával kapcsolatos részletes útmutatásért lásd: Az Okta által visszaadott jogkivonatok testreszabása.

5. lépés: A konfiguráció tesztelése

Indítsa el a Data API Buildert:
```
dab start
```
Szerezzen be egy tokent az identitásszolgáltatójától. Használja a szolgáltató SDK-ját vagy egy olyan eszközt, mint a Postman.
Ellenőrizze a jogkivonatot a jwt.io oldalán az ellenőrzés céljából.
- A aud jogcím megfelel a konfigurált célközönségnek
- A iss jogcím megegyezik a konfigurált kiállítóval
- A roles jogcím a várt értékeket tartalmazza

Az API meghívása:

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

Egyéni szerepkör használatához add meg a X-MS-API-ROLE fejlécet:

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

JWT-érvényesítési adatok

A Data API Builder a JWT alábbi szempontjait érvényesíti:

Ellenőriz	Leírás
Aláírás	Érvényesítve a konfigurált `jwt.issuer` szolgáltató által felderített aláíró kulcsokkal (OpenID Connect-metaadatok vagy JSON webkulcskészlet (JWKS))
Kibocsátó	Pontosan meg kell egyeznie a konfigurációval `jwt.issuer`
Hallgatóság	Pontosan meg kell egyeznie a konfigurációval `jwt.audience`
Lejárat	A token nem lehet lejárt (`exp` jogcím)
Nem korábban	A tokennek érvényesnek kell lennie (`nbf` igény, ha van)

Hibaelhárítás

tüneti	Lehetséges ok	Megoldás
`401 Unauthorized`	A kiállító eltérése	Ellenőrizze, hogy a `iss` kijelentés pontosan megegyezik (beleértve a záró perjelet is)
`401 Unauthorized`	Célközönség eltérése	Ellenőrizze, hogy a jogcím megfelel-e `aud` a konfigurált értéknek
`401 Unauthorized`	A jogkivonat lejárt	Új token beszerzése
`401 Unauthorized`	A metaadatok nem érhetők el	Győződjön meg arról, hogy a DAB el tud érni `<issuer>/.well-known/openid-configuration`
`403 Forbidden`	A szerepkör nem található a tokenben.	Szerepkör hozzáadása az idP-konfigurációhoz
`403 Forbidden`	Nem található `roles` igény	Állítsa be az identitásszolgáltatót, hogy egy `roles` állítást foglaljon bele
`403 Forbidden`	Helytelen igénynév	A DAB jogcímtípust `roles` használ (rögzített, nem konfigurálható)
`403 Forbidden`	Az Auth0 egyéni jogcíme észrevétlenül el lett hagyva	Az Auth0 elvetheti a nem névtérrel ellátott egyéni attribútumokat. Ellenőrizze, hogy a `roles` állítás szerepel-e a dekódolt tokenben a jwt.io oldalon. Lásd : Hitelesítés0: Szerepkörök hozzáadása művelettel

Fontos

A jogcím típusa roles minden szerepkör-ellenőrzéshez rögzített, és nem módosítható. Konfigurálja az identitásszolgáltatót úgy, hogy pontosan roles nevű jogcímadatot bocsásson ki. Az Auth0 felhasználóinak át kell tekinteniük a névtérütközést.

Gyakori kibocsátói formátumok

Szolgáltató	Kibocsátó formátuma
Okta	`https://<domain>.okta.com` vagy `https://<domain>.okta.com/oauth2/default`
Hitelesítés0	`https://<tenant>.auth0.com/` (jegyezze fel a záró perjelet)
Azure AD B2C	`https://<tenant>.b2clogin.com/<tenant-id>/v2.0/`
Keycloak	`https://<host>/realms/<realm>`

Teljes konfigurációs példa

Okta-konfiguráció

{
  "$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 konfiguráció

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

Visszajelzés

Hasznosnak találta ezt az oldalt?

Last updated on 2026-05-14

Egyéni JWT-hitelesítés konfigurálása (Okta, Hitelesítés0)

Hitelesítési folyamat

Előfeltételek

Rövid összefoglalás

1. lépés: Az identitásszolgáltató konfigurálása

Gyűjtendő értékek

Okta-példa

Auth0 példa

2. lépés: A Data API Builder konfigurálása

parancssori felület

Az eredményként kapott konfiguráció

3. lépés: Entitásengedélyek konfigurálása

parancssori felület

Az eredményként kapott konfiguráció

4. lépés: Szerepkörök konfigurálása az identitásszolgáltatóban

Okta: Csoportok hozzáadása szerepkörként

Hitelesítés: Szerepkörök hozzáadása művelettel

5. lépés: A konfiguráció tesztelése

JWT-érvényesítési adatok

Hibaelhárítás

Gyakori kibocsátói formátumok

Teljes konfigurációs példa

Okta-konfiguráció

Auth0 konfiguráció

Kapcsolódó tartalom

Visszajelzés

További források