Udostępnij przez

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.

Określanie roli użytkownika

Żaden role nie ma uprawnień domyślnych. Kiedy Konstruktor API danych określi regułę, jednostka permissions musi zdefiniować actions dla tej roli, aby żądanie zakończyło się pomyślnie.

Udostępniony token x-ms-api-role Dostarczone x-ms-api-role w tokenie Wynikowa rola
Nie. Nie. Nie. anonymous
Tak Nie. Nie. authenticated
Tak Tak Nie. Wyjątek
Tak Tak Tak x-ms-api-role wartość

Aby mieć rolę inną niż anonymous lub authenticated, nagłówek x-ms-api-role jest wymagany.

Uwaga / Notatka

Żądanie może mieć tylko jedną rolę. Nawet jeśli token wskazuje wiele ról, wartość x-ms-api-role określa, która rola jest przypisana do żądania.

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. Token dostępu dostarczony przez aplikację kliencką musi zawierać przypisania ról, które przedstawiają członkostwo użytkownika w rolach.
  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" ]
        }
    ]
}

W usłudze App Service użytkownik jest domyślnie członkiem roli anonimowej. Jeśli użytkownik jest uwierzytelniony, użytkownik jest członkiem ról anonymous i authenticated .

Ponieważ konstruktor interfejsu API danych ocenia żądania w kontekście pojedynczej roli, ocenia żądanie w kontekście roli authenticated systemu domyślnie.

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 -r 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" ]
  }]
}

Aby uprościć definicję uprawnień dla jednostki, załóżmy, że jeśli nie ma określonych uprawnień dla authenticated roli, używane są uprawnienia zdefiniowane dla anonymous roli. Przedstawiona book wcześniej konfiguracja umożliwia wszystkim anonimowym lub uwierzytelnionym użytkownikom wykonywanie operacji odczytu w jednostce book.

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

Wyrażenia zasad bazy danych umożliwiają jeszcze większe ograniczenie wyników. Zasady bazy danych tłumaczą wyrażenia na predykaty zapytań wykonywane względem bazy danych. Wyrażenia zasad bazy danych są obsługiwane dla następujących akcji:

  • utworzyć
  • odczyt
  • aktualizacja
  • usunąć

Ostrzeżenie

Akcja execute, używana z procedurami składowanymi, nie obsługuje zasad bazy danych.

Uwaga / Notatka

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

Aby uzyskać więcej informacji na temat zasad bazy danych, zobacz dokumentację pliku konfiguracji .

Przykład

Zasady bazy danych ograniczające read akcję dla consumer roli tak, aby zwracała rekordy tylko wtedy, gdy tytuł to "Przykładowy tytuł".

{
  "role": "consumer",
  "actions": [
    {
      "action": "read",
      "policy": {
        "database": "@item.title eq 'Sample Title'"
      }
    }
  ]
}

Treści powiązane

  • Last updated on