Omówienie autoryzacji

Autoryzacja określa, co uwierzytelnieni użytkownicy mogą wykonywać w aplikacji konstruktora interfejsu API danych. Podczas uwierzytelniania sprawdza , kto jest użytkownikiem, autoryzacja kontroluje, do czego może uzyskiwać dostęp i modyfikować.

Kompilator API danych używa procesu autoryzacji opartego na rolach. 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.

Kluczowe pojęcia dotyczące autoryzacji

Uprawnienia jednostki

Kontrolowanie operacji CRUD (tworzenie, odczyt, aktualizacja, usuwanie) na poziomie jednostki. Każdej roli można udzielić lub odmówić określonych akcji dotyczących określonych jednostek.

Kontrola dostępu oparta na rolach

Przypisz użytkowników do ról i przyznaj uprawnienia na podstawie członkostwa w rolach. Role upraszczają zarządzanie dużymi grupami użytkowników z podobnymi wzorcami dostępu.

Zabezpieczenia danych na poziomie wiersza

Filtruj dane na podstawie tożsamości użytkownika lub kontekstu sesji. Użytkownicy widzą tylko wiersze, do których mają uprawnienia dostępu, wymuszane na poziomie bazy danych.

Zasady interfejsu API

Zastosuj predykaty i filtry OData do odpowiedzi interfejsu API. Zasady automatycznie ograniczają wyniki zapytań na podstawie oświadczeń użytkowników i tożsamości.

Autoryzacja oparta na oświadczeniach

Aby określić dostęp, użyj oświadczeń z tokenów uwierzytelniania (na przykład grup, ról, atrybutów niestandardowych). Oświadczenia zapewniają elastyczne, precyzyjne decyzje dotyczące uprawnień.

Jak to działa

1. Użytkownik uwierzytelnia się przy użyciu jednej z obsługiwanych metod uwierzytelniania
2. System wyodrębnia oświadczenia z tokenu uwierzytelniania (role, grupy, organizacja itp.)
3. Reguły autoryzacji są oceniane względem oświadczeń użytkownika i żądanego zasobu
4. Dostęp jest udzielany lub odrzucany na podstawie uprawnień jednostki, zasad i reguł zabezpieczeń na poziomie wiersza

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 jest stosowana do dostawców JWT (JSON Web Token) nośników (na przykład EntraID/AzureAD i Custom), gdzie klient wysyła element Authorization: Bearer <token>.

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

Uwagi dotyczące dostawcy:

• Dostawcy usługi EasyAuth (na przykład AppService): nagłówki tworzone przez platformę (takie jak X-MS-CLIENT-PRINCIPAL) ustanawiają uwierzytelnianie, zamiast tokenu typu Bearer.
• Simulator: żądania są traktowane jak authenticated w przypadku 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

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.

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.

Akcje

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

Zasady bazy danych (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.

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

Dziedziczenie roli

DAB 2.0 wprowadza dziedziczenie uprawnień, więc nie trzeba powtarzać tego samego bloku uprawnień w każdej roli. Łańcuch dziedziczenia to:

named-role → authenticated → anonymous

• Jeśli authenticated nie jest jawnie skonfigurowany dla encji, dziedziczy z anonymous.
• Jeśli nazwana rola nie jest skonfigurowana, dziedziczy z authenticated, lub z anonymous, jeśli authenticated również jest nieobecna.

Uprawnienia można zdefiniować raz na anonymous, a każda szersza rola automatycznie uzyska ten sam dostęp, bez konieczności duplikowania.

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

W przypadku tej konfiguracji, anonymous, authenticated i dowolna nieskonfigurowana nazwana rola mogą odczytywać Book.

dab configure --show-effective-permissions służy do wyświetlania rozwiązanych uprawnień dla każdej jednostki po zastosowaniu dziedziczenia.

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

Model zabezpieczeń warstwowych

Konstruktor interfejsu API danych używa wielu warstw autoryzacji:

• Poziom jednostki: które jednostki i operacje są dostępne
• Poziom polityki: jakie dane są zwracane (filtrowanie na podstawie roszczeń)
• Poziom wiersza: baza danych stosuje filtrowanie za pomocą zabezpieczeń wierszowych
• Poziom interfejsu API: nagłówki HTTP i walidacja żądań

Następne kroki

• Dziedziczenie ról — budowanie hierarchii ról
• Zasady interfejsu API — stosowanie filtrów OData na podstawie oświadczeń
• Zabezpieczenia na poziomie wiersza — filtrowanie danych na poziomie bazy danych
• Najlepsze rozwiązania — wskazówki dotyczące wzmacniania zabezpieczeń