src/proto/grpc/auth/v1/authz_policy.proto

   1 // Copyright 2021 The gRPC Authors
   2 //
   3 // Licensed under the Apache License, Version 2.0 (the "License");
   4 // you may not use this file except in compliance with the License.
   5 // You may obtain a copy of the License at
   6 //
   7 //     http://www.apache.org/licenses/LICENSE-2.0
   8 //
   9 // Unless required by applicable law or agreed to in writing, software
  10 // distributed under the License is distributed on an "AS IS" BASIS,
  11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  12 // See the License for the specific language governing permissions and
  13 // limitations under the License.
  14
  15 syntax = "proto3";
  16
  17 package grpc.auth.v1;
  18
  19 // Peer specifies attributes of a peer. Fields in the Peer are ANDed together, once
  20 // we support multiple fields in the future.
  21 message Peer {
  22   // Optional. A list of peer identities to match for authorization. The principals
  23   // are one of, i.e., it matches if one of the principals matches. The field
  24   // supports Exact, Prefix, Suffix, and Presence matches.
  25   // - Exact match: "abc" will match on value "abc".
  26   // - Prefix match: "abc*" will match on value "abc" and "abcd".
  27   // - Suffix match: "*abc" will match on value "abc" and "xabc".
  28   // - Presence match: "*" will match when the value is not empty.
  29   repeated string principals = 1;
  30 }
  31
  32 // Specification of HTTP header match attributes.
  33 message Header {
  34   // Required. The name of the HTTP header to match. The following headers are *not*
  35   // supported: "hop-by-hop" headers (e.g., those listed in "Connection" header),
  36   // HTTP/2 pseudo headers (":"-prefixed), the "Host" header, and headers prefixed
  37   // with "grpc-".
  38   string key = 1;
  39
  40   // Required. A list of header values to match. The header values are ORed together,
  41   // i.e., it matches if one of the values matches. This field supports Exact,
  42   // Prefix, Suffix, and Presence match. Multi-valued headers are considered a single
  43   // value with commas added between values.
  44   // - Exact match: "abc" will match on value "abc".
  45   // - Prefix match: "abc*" will match on value "abc" and "abcd".
  46   // - Suffix match: "*abc" will match on value "abc" and "xabc".
  47   // - Presence match: "*" will match when the value is not empty.
  48   repeated string values = 2;
  49 }
  50
  51 // Request specifies attributes of a request. Fields in the Request are ANDed
  52 // together.
  53 message Request {
  54   // Optional. A list of paths to match for authorization. This is the fully
  55   // qualified name in the form of "/package.service/method". The paths are ORed
  56   // together, i.e., it matches if one of the paths matches. This field supports
  57   // Exact, Prefix, Suffix, and Presence matches.
  58   // - Exact match: "abc" will match on value "abc".
  59   // - Prefix match: "abc*" will match on value "abc" and "abcd".
  60   // - Suffix match: "*abc" will match on value "abc" and "xabc".
  61   // - Presence match: "*" will match when the value is not empty.
  62   repeated string paths = 1;
  63
  64   // Optional. A list of HTTP header key/value pairs to match against, for
  65   // potentially advanced use cases. The headers are ANDed together, i.e., it matches
  66   // only if *all* the headers match.
  67   repeated Header headers = 3;
  68 }
  69
  70 // Specification of rules.
  71 message Rule {
  72   // Required. The name of an authorization rule.
  73   // It is mainly for monitoring and error message generation.
  74   string name = 1;
  75
  76   // Optional. If not set, no checks will be performed against the source. An empty
  77   // rule is always matched (i.e., both source and request are empty).
  78   Peer source = 2;
  79
  80   // Optional. If not set, no checks will be performed against the request. An empty
  81   // rule is always matched (i.e., both source and request are empty).
  82   Request request = 3;
  83 }
  84
  85 // AuthorizationPolicy defines which principals are permitted to access which
  86 // resource. Resources are RPC methods scoped by services.
  87 //
  88 // In the following yaml policy example, a peer identity from ["admin1", "admin2", "admin3"]
  89 // is authorized to access any RPC methods in pkg.service, and peer identity "dev" is
  90 // authorized to access the "foo" and "bar" RPC methods.
  91 //
  92 // name: example-policy
  93 // allow_rules:
  94 // - name: admin-access
  95 //   source:
  96 //     principals:
  97 //     - "spiffe://foo.com/sa/admin1"
  98 //     - "spiffe://foo.com/sa/admin2"
  99 //     - "spiffe://foo.com/sa/admin3"
 100 //   request:
 101 //     paths: ["/pkg.service/*"]
 102 // - name: dev-access
 103 //   source:
 104 //     principals: ["spiffe://foo.com/sa/dev"]
 105 //   request:
 106 //     paths: ["/pkg.service/foo", "/pkg.service/bar"]
 107
 108 message AuthorizationPolicy {
 109   // Required. The name of an authorization policy.
 110   // It is mainly for monitoring and error message generation.
 111   string name = 1;
 112
 113   // Optional. List of deny rules to match. If a request matches any of the deny
 114   // rules, then it will be denied. If none of the deny rules matches or there are
 115   // no deny rules, the allow rules will be evaluated.
 116   repeated Rule deny_rules = 2;
 117
 118   // Required. List of allow rules to match. The allow rules will only be evaluated
 119   // after the deny rules. If a request matches any of the allow rules, then it will
 120   // allowed. If none of the allow rules matches, it will be denied.
 121   repeated Rule allow_rules = 3;
 122 }