Konfigurowanie niestandardowego uwierzytelniania JWT (Okta, Auth0)

Konstruktor interfejsu API danych obsługuje dostawców tożsamości innych firm za pośrednictwem niestandardowego dostawcy uwierzytelniania. Użyj tego podejścia, gdy organizacja używa dostawcy tożsamości zgodnego z protokołem Okta, Auth0 lub innego dostawcy tożsamości zgodnego z protokołem OAuth 2.0/OpenID Connect.

Przepływ uwierzytelniania

W przypadku niestandardowego dostawcy tożsamości aplikacja kliencka obsługuje uwierzytelnianie użytkowników, a następnie wysyła token dostępu do konstruktora interfejsu API danych:

Ilustracja niestandardowego przepływu uwierzytelniania JWT z zewnętrznym dostawcą tożsamości.

Phase	Co się stanie
Uwierzytelnianie użytkownika	Użytkownik loguje się za pośrednictwem dostawcy tożsamości (Okta, Auth0 itp.)
Pozyskiwanie tokenów	Aplikacja kliencka odbiera token dostępu od dostawcy tożsamości
Wywołanie interfejsu API	Klient wysyła token do DAB w nagłówku `Authorization`
Weryfikacja	DAB weryfikuje JWT (wystawca, odbiorca, podpis)
Authorization	DAB wyodrębnia role i ocenia uprawnienia

Wymagania wstępne

Konto u dostawcy tożsamości (takiego jak Okta, Auth0 itp.)
Aplikacja zarejestrowana u dostawcy tożsamości
Zainstalowany interfejs wiersza polecenia konstruktora interfejsu API danych (przewodnik instalacji)
Istniejąca dab-config.json z co najmniej jedną encją

Krótki przewodnik

Setting	Wartość
Provider	`Custom`
Wymagane do weryfikacji	`iss`, , `aud`, `exp`prawidłowy podpis
Wymagane do autoryzacji	`roles` oświadczenie zawierające wybraną rolę
Nagłówek tokenu	`Authorization: Bearer <token>`
Typ oświadczenia roli	`roles` (naprawiono, nie można skonfigurować)
Nagłówek wyboru roli	`X-MS-API-ROLE`

Krok 1. Konfigurowanie dostawcy tożsamości

Dokładne kroki zależą od dostawcy. Oto potrzebne wartości kluczy:

Wartości do zebrania

Wartość	Gdzie go znaleźć	Służy do
Adres URL wystawcy	Dokumentacja dostawcy lub punkt końcowy metadanych OAuth	DAB `jwt.issuer` (używany jako autorytet JWT)
Audiencja	Identyfikator klienta aplikacji lub niestandardowy identyfikator API	DAB `jwt.audience`

Uwaga / Notatka

DAB używa skonfigurowanego jwt.issuer jako autorytet JWT. Klucze podpisywania są odnajdywane automatycznie za pośrednictwem standardowych metadanych openID Connect (zazwyczaj <issuer>/.well-known/openid-configuration).

Przykład usługi Okta

Zaloguj się do konsoli administracyjnej usługi Okta.
Przejdź do Aplikacje>Aplikacje.
Utwórz lub wybierz aplikację.
Zanotuj identyfikator klienta (użyj go jako odbiorcy).
Wystawcą zazwyczaj jest https://<your-domain>.okta.com.

Przykład uwierzytelniania Auth0

Zaloguj się do pulpitu nawigacyjnego Auth0.
Przejdź do pozycji Aplikacje>Interfejsy API.
Utwórz lub wybierz interfejs API.
Zanotuj identyfikator (użyj jako odbiorców).
Twój wystawca to https://<your-tenant>.auth0.com/.

Ważne

Data API builder używa stałego typu oświadczenia roles dla autoryzacji opartej na rolach. Nie można skonfigurować tej wartości. Jeśli dostawca tożsamości przypisuje role w innym żądaniu (takim jak groups lub permissions), musisz skonfigurować dostawcę, aby także emitował żądanie roles, lub użyć czynności po zalogowaniu, aby skopiować wartości do żądania roles.

Krok 2. Konfigurowanie konstruktora interfejsu API danych

Ustaw dostawcę uwierzytelniania na Custom i skonfiguruj ustawienia 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>/"

Konfiguracja wyniku

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

Krok 3. Konfigurowanie uprawnień jednostki

Zdefiniuj uprawnienia dla ról przypisywanych przez dostawcę tożsamości:

CLI

Bash
Wiersz polecenia

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

Konfiguracja wyniku

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

Krok 4. Konfigurowanie ról u dostawcy tożsamości

DAB oczekuje ról w oświadczeniu roles. Skonfiguruj dostawcę tożsamości, aby uwzględnił to oświadczenie.

Okta: Dodawanie grup jako ról

W konsoli administracyjnej usługi Okta przejdź do Zabezpieczenia>API.
Wybierz serwer autoryzacji.
Przejdź do karty Roszczenia.
Dodaj oświadczenie:
- Nazwa: roles
- Uwzględnij w typie tokenu: Token dostępu
- Typ wartości: Grupy
- Filtr: wybierz grupy do uwzględnienia

Auth0: Dodaj role za pomocą akcji

Na pulpicie nawigacyjnym Auth0 przejdź dobiblioteki>.
Utwórz nową czynność (wyzwalacz po zalogowaniu).
Dodaj kod, aby uwzględnić role:

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

Wdróż akcję i dodaj ją do przepływu logowania.

Wskazówka

Aby uzyskać szczegółowe wskazówki dotyczące konfigurowania oświadczeń JWT za pomocą usługi Okta, zobacz Implementowanie zaawansowanych oświadczeń JWT przy użyciu zestawu SDK usługi Okta.

Krok 5. Testowanie konfiguracji

Uruchom konstruktora interfejsu API danych:
```
dab start
```
Uzyskaj token od dostawcy tożsamości. Użyj zestawu SDK dostawcy lub narzędzia, takiego jak Postman.
Sprawdź token pod adresem jwt.io , aby sprawdzić:
- Oświadczenie aud pasuje do Twojej skonfigurowanej grupy odbiorców
- Oświadczenie iss jest zgodne ze skonfigurowanym wystawcą
- Oświadczenie roles zawiera oczekiwane wartości

Wywołaj interfejs API:

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

Aby użyć roli niestandardowej, dołącz nagłówek X-MS-API-ROLE.

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

Szczegóły weryfikacji JWT

Konstruktor API danych weryfikuje te aspekty zestawu JWT:

Sprawdź	Description
Podpis	Weryfikowane przy użyciu kluczy podpisywania odnalezionych za pośrednictwem skonfigurowanego `jwt.issuer` urzędu (metadane OpenID Connect / JWKS)
Emitent	Musi dokładnie odpowiadać konfiguracji `jwt.issuer`.
Audiencja	Musi dokładnie odpowiadać konfiguracji `jwt.audience`
Data ważności	Token nie może być wygasły (`exp` oświadczenie)
Nie wcześniej	Token musi być prawidłowy (`nbf` oświadczenie, jeśli istnieje)

Rozwiązywanie problemów

Objaw	Możliwa przyczyna	Rozwiązanie
`401 Unauthorized`	Niezgodność wystawcy	`iss` Sprawdź, czy oświadczenie jest dopasowane idealnie (w tym ukośnik końcowy)
`401 Unauthorized`	Niezgodność odbiorców	Sprawdź, `aud` czy twierdzenie jest zgodne ze skonfigurowaną wartością
`401 Unauthorized`	Token wygasł	Uzyskiwanie nowego tokenu
`401 Unauthorized`	Metadane są niedostępne	Upewnij się, że DAB może dotrzeć `<issuer>/.well-known/openid-configuration`
`403 Forbidden`	Rola nie jest zawarta w tokenie	Dodaj rolę do konfiguracji IdP
`403 Forbidden`	Brak oświadczenia ról	Skonfiguruj swojego dostawcę tożsamości, aby uwzględnić `roles` oświadczenie
`403 Forbidden`	Nieprawidłowa nazwa oświadczenia	DAB używa typu roszczenia `roles` (stały, nieskonfigurowalny)

Ważne

DAB obecnie używa typu roles roszczenia dla wszystkich sprawdzania ról. Ta wartość jest zakodowana na stałe i nie można jej zmienić na groups, permissionslub inne nazwy oświadczeń. Skonfiguruj dostawcę tożsamości, aby emitować role w atrybucie nazwanym roles.

Typowe formaty emitentów

Provider	Format wystawcy
Okta	`https://<domain>.okta.com` lub `https://<domain>.okta.com/oauth2/default`
Auth0 powiedział:	`https://<tenant>.auth0.com/` (zwróć uwagę na końcowy ukośnik)
Azure AD B2C	`https://<tenant>.b2clogin.com/<tenant-id>/v2.0/`
Keycloak	`https://<host>/realms/<realm>`

Kompletny przykład konfiguracji

Konfiguracja usługi 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"]
        }
      ]
    }
  }
}

Konfiguracja uwierzytelniania 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": ["*"]
        }
      ]
    }
  }
}

Sprzężenie zwrotne

Czy ta strona była pomocna?

Last updated on 2026-01-23

Udostępnij przez

Konfigurowanie niestandardowego uwierzytelniania JWT (Okta, Auth0)

Przepływ uwierzytelniania

Wymagania wstępne

Krótki przewodnik

Krok 1. Konfigurowanie dostawcy tożsamości

Wartości do zebrania

Przykład usługi Okta

Przykład uwierzytelniania Auth0

Krok 2. Konfigurowanie konstruktora interfejsu API danych

CLI

Konfiguracja wyniku

Krok 3. Konfigurowanie uprawnień jednostki

CLI

Konfiguracja wyniku

Krok 4. Konfigurowanie ról u dostawcy tożsamości

Okta: Dodawanie grup jako ról

Auth0: Dodaj role za pomocą akcji

Krok 5. Testowanie konfiguracji

Szczegóły weryfikacji JWT

Rozwiązywanie problemów

Typowe formaty emitentów

Kompletny przykład konfiguracji

Konfiguracja usługi Okta

Konfiguracja uwierzytelniania Auth0

Treści powiązane

Sprzężenie zwrotne

Dodatkowe źródła