einride / iam-go

An opinionated Open Source implementation of the google.iam APIs on top of Cloud Spanner.

IAM Go

An opinionated Open Source implementation of the google.iam.v1.IAMPolicy service API, using Cloud Spanner for storage.

Usage

1) Install

$ go get go.einride.tech/iam

2) Include the IAMPolicy mixin in your gRPC service

See google.iam.v1.IAMPolicy.

package your.pkg;

import "google/iam/v1/iam_policy.proto";
import "google/iam/v1/policy.proto";

service YourService {
  /* ... */

  rpc SetIamPolicy(google.iam.v1.SetIamPolicyRequest) returns (google.iam.v1.Policy);
  rpc GetIamPolicy(google.iam.v1.GetIamPolicyRequest) returns (google.iam.v1.Policy);
  rpc TestIamPermissions(google.iam.v1.TestIamPermissionsRequest) returns (google.iam.v1.TestIamPermissionsResponse);
}

3) Embed the IAMServer implementation in your server

See iamspanner.IAMServer.

// Server implements your gRPC API.
type Server struct {
	*iamspanner.IAMServer
	// ...
}

// Server now also implements the iam.IAMPolicyServer mixin.
var _ iam.IAMPolicyServer = &Server{}

4) Include the IAM policy bindings table in your Spanner SQL schema

See schema.sql.

5) Annotate your gRPC methods

Buf annotations for rpc method authorization are described in annotations.proto

package your.pkg;

import "einride/iam/v1/annotations.proto";

service YourService {
  rpc YourMethod(YourMethodRequest) returns YourMethodResponse {
      option (einride.iam.v1.method_authorization) = {
        permission: "namespace.entity.method"
        before: {
          expression: "test(caller, request.entity)" // iamcel expression
          description: "The caller must have method permission against the entity"
        }
      };
    };
}

message YourMethodRequest {
  string entity = 1 [
    (google.api.resource_reference) = {
      type: "example.com/Entity"
    }
  ];
};

package your.pkg;

import "einride/iam/v1/annotations.proto";

service YourService {
  rpc YourMethod(YourMethodRequest) returns YourMethodResponse {
      option (einride.iam.v1.method_authorization) = {
        resource_permissions {
          resource_permission {
            resource: {
              type: "example.com/Entity1"
            }
            permission: "namespace.entity1.method"
          }
          resource_permission {
            resource: {
              type: "example.com/Entity2"
            }
            permission: "namespace.entity2.method"
          }
        }
        after: {
          expression: "test_all(caller, response.entities)" // iamcel expression
          description: "The caller must have method permission against all entities"
        }
      };
    };
}

message YourMethodResponse {
  // Elements in this list are either Entity1 or Entity2 references
  repeated string entities = 1;
};

Expresssions in the method_authorization annotation use cel-go with iamcel extensions. The iamcel extensions provide the following cel functions.

test(caller Caller, resource string) bool

Tests callers permissions against resource.

test_all(caller Caller, resources []string) bool

Tests callers permissions against all resources. This test asserts that the caller has the permission against all resources.

test_any(caller Caller, resources []string) bool

Tests callers permissions against any resources. This test asserts that the caller has the permission against at least one resource.

ancestor(resource string, pattern string) string

Resolves an ancestor of resource using pattern. An input of ancestor("foo/1/bar/2", "foo/{foo}") will yield the result "foo/1".

join(parent string, resource string) string

Joins a resource name with a parent resource name. An input of join("foo/1", "bar/2") will yield the result "foo/1/bar/2".

caller.member(kind string) string

Returns the first IAM member value from the caller's member list which matches the member kind, or fails if there are no such kind.

6) Generate authorization middleware

Coming soon.

iam-go's Issues

Add bazel support go protoc-gen-go-iam

As the title, could you guys please to add bazel support for this project.

how should I use this library

syntax = "proto3";

package feedback.v1;

import "einride/iam/v1/annotations.proto";
import "google/api/annotations.proto";
import "google/api/client.proto";
import "google/api/field_behavior.proto";
import "google/api/resource.proto";
import "google/protobuf/empty.proto";
import "google/protobuf/field_mask.proto";
import "google/protobuf/timestamp.proto";

option go_package = "example/genproto/feedback/v1;feedbackv1";

service FeedbackService {
  // GetFeedback ....
  rpc GetFeedback(GetFeedbackRequest) returns (Feedback) {
    option (google.api.http) = {
      get: "/v1/{name=users/*/feedbacks/*}",
    };
    option (google.api.method_signature) = "name";
    option (einride.iam.v1.method_authorization) = {
      permission: "example.feedbacks.get"
      before {
        expression: "test(caller, request.name)"
        description: "The caller must have permission to get the feedbacks."
      }
    };
  }
}

version: v1
name: buf.build/example/api
deps:
  - buf.build/googleapis/googleapis
  - buf.build/grpc-ecosystem/grpc-gateway
  - buf.build/einride/iam
lint:
  use:
    - DEFAULT
  except:
    - RPC_RESPONSE_STANDARD_NAME
    - RPC_REQUEST_RESPONSE_UNIQUE
  rpc_allow_google_protobuf_empty_requests: true
  rpc_allow_google_protobuf_empty_responses: true

I tried to build via buf and got an error

$ buf generate
protoc-gen-go-grpc: unable to determine Go import path for "einride/iam/v1/annotations.proto"

Please specify either:
        • a "go_package" option in the .proto source file, or
        • a "M" argument on the command line.

See https://developers.google.com/protocol-buffers/docs/reference/go-generated#package for more information.

Failure: plugin go-grpc: exit status 1; signal: killed

Try adding the following to buf.gen.yaml

version: v1
managed:
  enabled: true
  go_package_prefix:
    default: example/genproto
    except:
      - buf.build/googleapis/googleapis

Execute buf generate successfully

But there is a new problem with go build, the relevant package is not found

$ go build ./cmd/apiserver 
genproto/feedback/v1/feedback.pb.go:10:2: package example/genproto/einride/iam/v1 is not in GOROOT (/usr/local/opt/go/libexec/src/example/genproto/einride/iam/v1)