Udostępnij za pośrednictwem

Autoryzacja i role w konstruktorze interfejsu API danych

  • Artykuł

Konstruktor interfejsu API danych używa przepływu pracy autoryzacji opartej na rolach. Każde żądanie przychodzące, uwierzytelnione lub nie, jest przypisane do roli. Role systemowe mogą być rolami systemu lub rolami użytkownika. Przypisana rola jest następnie sprawdzana względem zdefiniowanych uprawnień określonych w pliku konfiguracji , aby zrozumieć, jakie akcje, pola i zasady są dostępne dla tej roli dla żądanej jednostki.

Role

Role ustawiają kontekst uprawnień, w którym ma zostać wykonane żądanie. Dla każdej jednostki zdefiniowanej w konfiguracji środowiska uruchomieniowego można zdefiniować zestaw ról i skojarzonych uprawnień, które określają sposób uzyskiwania dostępu do jednostki zarówno w punktach końcowych REST, jak i GraphQL.

Konstruktor interfejsu API danych ocenia żądania w kontekście jednej roli:

  • anonymous gdy nie zostanie wyświetlony token dostępu.
  • authenticated po wyświetleniu prawidłowego tokenu dostępu.
  • <CUSTOM_USER_ROLE> po wyświetleniu prawidłowego tokenu dostępu iX-MS-API-ROLE dołączeniu nagłówka HTTP określającą rolę użytkownika, która jest również uwzględniona w oświadczeniu tokenu roles dostępu.

Role nie są addytywne, co oznacza, że użytkownik będący członkiem obu Role1 ról i Role2 nie dziedziczy uprawnień skojarzonych z obiem rolami.

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 osoby żądającej oznaczonej w tokenach dostępu. Istnieją dwie role systemowe: anonymous i authenticated.

Rola systemu anonimowego

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

Przykład

Poniższa konfiguracja środowiska uruchomieniowego konstruktora interfejsu API danych pokazuje jawne skonfigurowanie roli anonymous systemu w celu uwzględnienia dostępu do odczytu do jednostki Book:

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

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

Uwierzytelniona rola systemu

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

Przykład

Poniższa konfiguracja środowiska uruchomieniowego konstruktora interfejsu API danych pokazuje jawne skonfigurowanie roli authenticated systemu w celu uwzględnienia dostępu do odczytu do jednostki Book:

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

Role użytkownika

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ć oświadczenia roli, które zawierają listę członkostwa w roli użytkownika.
  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 przedstawiono żą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 Static Web Apps użytkownik jest domyślnie członkiem roli anonimowej. Jeśli użytkownik jest uwierzytelniony, użytkownik jest członkiem zarówno ról, jak anonymous i authenticated .

Gdy aplikacja kliencka wysyła uwierzytelnione żądanie do konstruktora interfejsu API danych wdrożonego przy użyciu Static Web Apps Połączenia z bazą danych (wersja zapoznawcza), aplikacja kliencka dostarcza token dostępu, który Static Web Apps przekształca się w kod JSON:

{
  "identityProvider": "azuread",
  "userId": "d75b260a64504067bfc5b2905e3b8182",
  "userDetails": "username",
  "userRoles": ["anonymous", "authenticated", "author"]
}

Ponieważ konstruktor interfejsu API danych ocenia żądania w kontekście pojedynczej roli, domyślnie ocenia żądanie w kontekście roli authenticated 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ładowe żądanie, w tym token dostępu i X-MS-API-ROLE nagłówek HTTP:

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 oświadczenie dostarczonego tokenu roles dostępu nie zawiera roli wymienionej w nagłówku X-MS-API-ROLE .

Uprawnienia

Opis uprawnień:

  • Kto może wysyłać żądania do jednostki na podstawie członkostwa w roli?
  • 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ą w wynikach zwracanych przez żądanie?

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

Ważne

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

  • Domyślnie rola anonymous systemowa lub authenticated
  • Po dołączeniu rola ustawiona w nagłówku X-MS-API-ROLE HTTP.

Zabezpieczenie domyślne

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ą one przywoływalne w konfiguracji środowiska uruchomieniowego.

Uprawnienia muszą być jawnie skonfigurowane

Aby zezwolić na nieuwierzytelniony dostęp do jednostki, anonymous rola musi być jawnie zdefiniowana w uprawnieniach jednostki. Na przykład uprawnienia jednostki są jawnie ustawione, book 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. Pokazana book wcześniej konfiguracja umożliwia każdemu anonimowemu lub uwierzytelnionemu użytkownikowi wykonywanie operacji odczytu w jednostce book .

Gdy 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 anonymous ról i authenticated . Co najmniej jedna rola użytkownika może być zdefiniowana w konfiguracji uprawnień jednostki, a wszystkie inne niezdefiniowane role, system lub użytkownik są automatycznie odrzucane.

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

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

Uwaga

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 kontrola dostępu nadal jest wymuszana przez konfigurację uprawnień zgodnie z wcześniejszym opisem.

Akcje

Akcje opisują dostępność jednostki w zakresie roli. Akcje można określić indywidualnie lub za pomocą skrótu z symbolem 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 pól

Możesz skonfigurować, które pola 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 w free-access roli wykonywanie operacji odczytu w programie Column3. Odwołania do Column3 żądań GET (punktu końcowego REST) lub zapytań (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

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 kontrola dostępu nadal jest wymuszana przez konfigurację uprawnień zgodnie z opisem tutaj.

Zabezpieczenia na poziomie elementu

Wyrażenia zasad bazy danych umożliwiają dalsze 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 w przypadku następujących akcji:

  • create
  • odczyt
  • update
  • delete

Ostrzeżenie

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

Uwaga

Zasady bazy danych nie są obecnie obsługiwane przez usługę CosmosDB for NoSQL.

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

Przykład

Zasady bazy danych ograniczające read akcję roli consumer tylko do zwracania rekordów, w których tytuł to "Przykładowy tytuł".

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

Zawartość pokrewna