Udostępnij za pośrednictwem

Autoryzacja i role w narzędziu Data API Builder

Narzędzie do budowy API danych używa autoryzacji na podstawie ról. Każde żądanie przychodzące, uwierzytelnione lub nie, jest przypisane do roli. Role mogą być rolami systemowym lub rolami użytkownika. Przypisana rola jest następnie sprawdzana względem zdefiniowanych uprawnień określonych w konfiguracji, aby zrozumieć, jakie akcje, pola i zasady są dostępne dla tej roli dla żądanej jednostki.

Ilustracja przedstawiająca sposób, w jaki konstruktor interfejsu API danych wybiera rolę i ocenia uprawnienia do żądania.

Określanie roli użytkownika

Żadna rola nie ma uprawnień domyślnych. Gdy konstruktor interfejsu API danych określi rolę, permissions jednostki musi zdefiniować actions dla tej roli, aby żądanie zakończyło się pomyślnie.

Następująca macierz oceny ról dotyczy dostawców tokenu JWT (na przykład EntraID/AzureAD i Custom), gdzie klient wysyła Authorization: Bearer <token>.

Podany token elementu nośnego X-MS-API-ROLE Dostarczone Żądana rola obecna w zadaniu tokenu roles Efektywna rola/wynik
Nie. Nie. N/A Anonymous
Tak (prawidłowe) Nie. N/A Authenticated
Tak (prawidłowe) Tak Nie. Odrzucono (403 Zabronione)
Tak (prawidłowe) Tak Tak X-MS-API-ROLE wartość
Tak (nieprawidłowe) Jakikolwiek N/A Odrzucono (401 Brak autoryzacji)

Aby użyć roli innej niż Anonymous lub Authenticated, X-MS-API-ROLE nagłówek jest wymagany.

Uwaga / Notatka

Żądanie może być skojarzone z wieloma rolami w uwierzytelnionym podmiocie. Jednak konstruktor interfejsu API danych ocenia uprawnienia i zasady w kontekście dokładnie jednej efektywnej roli. Gdy jest podany, nagłówek X-MS-API-ROLE wybiera, która rola jest używana.

Uwagi dotyczące dostawcy:

  • Dostawcy usługi EasyAuth (na przykład AppService): uwierzytelnianie można ustanowić za pomocą nagłówków wstrzykiwanych przez platformę (na przykład X-MS-CLIENT-PRINCIPAL) zamiast tokenu nosiciela.
  • Simulator: żądania są traktowane jako uwierzytelnione na potrzeby programowania/testowania bez weryfikowania rzeczywistego tokenu.

Role systemowe

Role systemowe są wbudowane role rozpoznawane przez konstruktora interfejsu API danych. Rola systemowa jest automatycznie przypisywana do osoby żądającej niezależnie od członkostwa w roli osoby żądającej oznaczonej w tokenach dostępu. Istnieją dwie role systemowe: Anonymous i Authenticated.

Rola systemu anonimowego

Anonymous Rola systemowa jest przypisywana do żądań wykonywanych przez nieuwierzytelnionych użytkowników. Jednostki zdefiniowane przez konfigurację środowiska uruchomieniowego muszą zawierać uprawnienia dla Anonymous roli, jeśli żądany jest nieuwierzytelniony dostęp.

Przykład

Następująca konfiguracja środowiska uruchomieniowego konstruktora interfejsu API danych pokazuje jawne skonfigurowanie roli Anonymous systemu w celu uwzględnienia dostępu odczytu do encji Book:

"Book": {
    "source": "books",
    "permissions": [
        {
            "role": "Anonymous",
            "actions": [ "read" ]
        }
    ]
}

Gdy aplikacja kliencka wysyła żądanie dostępu do obiektu Książki w imieniu nieuwierzytelnionego użytkownika, aplikacja nie powinna zawierać nagłówka Authorization HTTP.

Uwierzytelniona rola systemu

Authenticated Rola systemowa jest przypisywana do żądań wykonywanych przez uwierzytelnionych użytkowników.

Przykład

Następująca konfiguracja środowiska uruchomieniowego konstruktora interfejsu API danych pokazuje jawne skonfigurowanie roli Authenticated systemu w celu uwzględnienia dostępu odczytu do encji Book:

"Book": {
    "source": "books",
    "permissions": [
        {
            "role": "Authenticated",
            "actions": [ "read" ]
        }
    ]
}

Role użytkowników

Role użytkownika to role niesystemowe przypisane do użytkowników w ramach dostawcy tożsamości ustawionego w konfiguracji środowiska uruchomieniowego. Aby konstruktor interfejsu API danych oceniał żądanie w kontekście roli użytkownika, należy spełnić dwa wymagania:

  1. Uwierzytelniony podmiot musi zawierać twierdzenia dotyczące ról, które określają członkostwo użytkownika w roli (na przykład twierdzenie JWT roles).
  2. Aplikacja kliencka musi zawierać nagłówek X-MS-API-ROLE HTTP z żądaniami i ustawić wartość nagłówka jako żądaną rolę użytkownika.

Przykład oceny roli

W poniższym przykładzie pokazano żądania wysyłane do Book jednostki skonfigurowanej w konfiguracji środowiska uruchomieniowego konstruktora interfejsu API danych w następujący sposób:

"Book": {
    "source": "books",
    "permissions": [
        {
      "role": "Anonymous",
            "actions": [ "read" ]
        },
        {
      "role": "Authenticated",
            "actions": [ "read" ]
        },
        {
            "role": "author",
            "actions": [ "read" ]
        }
    ]
}

Konstruktor interfejsu API danych ocenia żądania w kontekście pojedynczej efektywnej roli. Jeśli żądanie jest uwierzytelnione, a nagłówek X-MS-API-ROLE nie został podany, kompilator API danych domyślnie ocenia żądanie w kontekście Authenticated roli systemu.

Jeśli żądanie aplikacji klienckiej zawiera również nagłówek X-MS-API-ROLE HTTP z wartością author, żądanie jest oceniane w kontekście author roli. Przykład żądania zawierający token dostępu i nagłówek HTTP X-MS-API-ROLE:

curl -k -X GET \
  -H 'Authorization: Bearer ey...' \
  -H 'X-MS-API-ROLE: author' \
  https://localhost:5001/api/Book

Ważne

Żądanie aplikacji klienckiej jest odrzucane, gdy dostarczony token dostępu roles nie zawiera roli wymienionej w nagłówku X-MS-API-ROLE.

Uprawnienia

Opis uprawnień:

  • Kto może wysyłać żądania dotyczące jednostki w oparciu o członkostwo w rolach?
  • Jakie akcje (tworzenie, odczytywanie, aktualizowanie, usuwanie i wykonywanie) użytkownik może wykonać?
  • Które pola są dostępne dla określonej akcji?
  • Które dodatkowe ograniczenia istnieją dla wyników zwróconych przez żądanie?

Składnia definiowania uprawnień jest opisana w artykule dotyczącym konfiguracji środowiska uruchomieniowego.

Ważne

W konfiguracji uprawnień pojedynczej jednostki może być zdefiniowanych wiele ról. Jednak żądanie jest oceniane tylko w kontekście pojedynczej roli:

  • Domyślnie rola Anonymous systemowa lub Authenticated
  • Po dołączeniu rola jest ustawiana w nagłówku X-MS-API-ROLE HTTP.

Domyślnie zabezpieczone

Domyślnie jednostka nie ma skonfigurowanych uprawnień, co oznacza, że nikt nie może uzyskać dostępu do jednostki. Ponadto konstruktor interfejsu API danych ignoruje obiekty bazy danych, gdy nie są przywoływalne w konfiguracji środowiska uruchomieniowego.

Uprawnienia muszą być jawnie skonfigurowane

Aby zezwolić na nieuwierzytelniony dostęp do encji, rola Anonymous musi być jawnie zdefiniowana w uprawnieniach encji. Na przykład uprawnienia encji book są jawnie ustawione, aby zezwolić na nieuwierzytelniony dostęp do odczytu:

"book": {
  "source": "dbo.books",
  "permissions": [{
    "role": "Anonymous",
    "actions": [ "read" ]
  }]
}

Jeśli chcesz, aby zarówno użytkownicy nieuwierzytelnieni, jak i uwierzytelnieni mieli dostęp, jawnie przyznaj uprawnienia do obu ról systemowych (Anonymous i Authenticated).

Jeśli operacje odczytu powinny być ograniczone tylko do uwierzytelnionych użytkowników, należy ustawić następującą konfigurację uprawnień, co powoduje odrzucenie nieuwierzytelnionych żądań:

"book": {
  "source": "dbo.books",
  "permissions": [{
    "role": "Authenticated",
    "actions": [ "read" ]
  }]
}

Jednostka nie wymaga i nie jest wstępnie skonfigurowana z uprawnieniami dla ról Anonymous i Authenticated. Jedna lub więcej ról użytkownika może być zdefiniowana w ramach konfiguracji uprawnień jednostki, a wszystkie inne niezdefiniowane role, niezależnie od tego, czy są to role systemowe czy określone przez użytkownika, są automatycznie odrzucane.

W poniższym przykładzie rola administrator użytkownika jest jedyną zdefiniowaną rolą book dla jednostki. Użytkownik musi być członkiem roli administrator i uwzględnić tę rolę w nagłówku HTTP X-MS-API-ROLE, aby operować na jednostce book.

"book": {
  "source": "dbo.books",
  "permissions": [{
    "role": "administrator",
    "actions": [ "*" ]
  }]
}

Uwaga / Notatka

Aby wymusić kontrolę dostępu dla zapytań GraphQL podczas korzystania z konstruktora interfejsu API danych w usłudze Azure Cosmos DB, należy użyć @authorize dyrektywy w podanym pliku schematu GraphQL. Jednak w przypadku mutacji i filtrów graphQL w zapytaniach GraphQL konfiguracja uprawnień nadal wymusza kontrolę dostępu zgodnie z wcześniejszym opisem.

Czynności

Akcje opisują dostępność jednostki w kontekście roli. Akcje można określić pojedynczo lub za pomocą skrótu z symbolami wieloznacznymi: * (gwiazdka). Skrót wieloznaczny reprezentuje wszystkie akcje obsługiwane dla typu jednostki:

  • Tabele i widoki: create, , read, updatedelete
  • Procedury składowane: execute

Aby uzyskać więcej informacji na temat akcji, zobacz dokumentację pliku konfiguracji .

Dostęp do pola

Możesz skonfigurować pola, które powinny być dostępne dla akcji. Można na przykład ustawić pola do uwzględnienia i wykluczenia z read akcji.

Poniższy przykład uniemożliwia użytkownikom pełniącym rolę free-access wykonywanie operacji odczytu na Column3. Odwołania do Column3 w żądaniach GET (punkt końcowy REST) lub w zapytaniach (punkt końcowy GraphQL) powodują odrzucenie żądania:

    "book": {
      "source": "dbo.books",
      "permissions": [
        {
          "role": "free-access",
          "actions": [
            "create",
            "update",
            "delete",
            {
              "action": "read",
              "fields": {
                "include": [ "Column1", "Column2" ],
                "exclude": [ "Column3" ]
              }
            }
          ]
        }
      ]
    }

Uwaga / Notatka

Aby wymusić kontrolę dostępu dla zapytań GraphQL podczas korzystania z konstruktora interfejsu API danych w usłudze Azure Cosmos DB, należy użyć @authorize dyrektywy w podanym pliku schematu GraphQL. Jednak w przypadku mutacji i filtrów graphQL w zapytaniach GraphQL konfiguracja uprawnień nadal wymusza kontrolę dostępu zgodnie z opisem w tym miejscu.

Zabezpieczenia na poziomie elementu

Zasady bazy danych umożliwiają filtrowanie wyników na poziomie wiersza. Zasady tłumaczą się na predykaty zapytań, które ocenia baza danych, zapewniając użytkownikom dostęp tylko do autoryzowanych rekordów.

Obsługiwane akcje Niewspierane
read, updatedelete create, execute

Uwaga / Notatka

Usługa Azure Cosmos DB for NoSQL nie obsługuje obecnie zasad bazy danych.

Aby uzyskać szczegółowe kroki konfiguracji, odwołanie do składni i przykłady, zobacz Konfigurowanie zasad bazy danych.

Szybki przykład
{
  "role": "consumer",
  "actions": [
    {
      "action": "read",
      "policy": {
        "database": "@item.ownerId eq @claims.userId"
      }
    }
  ]
}

Treści powiązane

  • Last updated on