goto / shield

Shield is a role-based cloud-native user management system, identity & access proxy, and authorization server for your applications and API endpoints.

Shield

Shield is a cloud native role-based authorization aware server and reverse-proxy system. With Shield, you can assign roles to users or groups of users to configure policies that determine whether a particular user has the ability to perform a certain action on a given resource.

Key Features

Discover why users choose Shield as their authorization proxy

• Policy Management: Policies help you assign various roles to users/groups that determine their access to various resources
• Group Management: Group is nothing but another word for team. Shield provides APIs to add/remove users to/from a group, fetch list of users in a group along with their roles in the group, and fetch list of groups a user is part of.
• Activity Logs: Shield has APIs that store and retrieve all the access related logs. You can see who added/removed a user to/from group in these logs.
• Reverse Proxy: In addition to configuring access management, you can also use Shield as a reverse proxy to directly protect your endpoints by configuring appropriate permissions for them.
• Google IAP: Shield also utilizes Google IAP as an authentication mechanism. So if your services are behind a Google IAP, Shield will seemlessly integrate with it.
• Runtime: Shield can run inside containers or VMs in a fully managed runtime environment like Kubernetes. Shield also depends on a Postgres server to store data.

How can I get started?

• Guides provide guidance on how to use Shield and configure it to your needs
• Concepts descibe the primary concepts and architecture behind Shield
• Reference contains the list of all the APIs that Shield exposes
• Contributing contains resources for anyone who wants to contribute to Shield

Installation

Install Shield on macOS, Windows, Linux, OpenBSD, FreeBSD, and on any machine. Refer this for installations.

Binary (Cross-platform)

Download the appropriate version for your platform from releases page. Once downloaded, the binary can be run from anywhere. You don’t need to install it into a global location. This works well for shared hosts and other systems where you don’t have a privileged account. Ideally, you should install it somewhere in your PATH for easy use. /usr/local/bin is the most probable location.

macOS

shield is available via a Homebrew Tap, and as downloadable binary from the releases page:

brew install goto/tap/shield

To upgrade to the latest version:

brew upgrade shield

Check for installed shield version

shield version

Linux

shield is available as downloadable binaries from the releases page. Download the .deb or .rpm from the releases page and install with sudo dpkg -i and sudo rpm -i respectively.

Windows

shield is available via scoop, and as a downloadable binary from the releases page:

scoop bucket add shield https://github.com/goto/scoop-bucket.git

To upgrade to the latest version:

scoop update shield

Docker

We provide ready to use Docker container images. To pull the latest image:

docker pull gotocompany/shield:latest

To pull a specific version:

docker pull gotocompany/shield:v0.3.2

If you like to have a shell alias that runs the latest version of shield from docker whenever you type shield:

mkdir -p $HOME/.config/gotocompany
alias shield="docker run -e HOME=/tmp -v $HOME/.config/gotocompany:/tmp/.config/gotocompany --user $(id -u):$(id -g) --rm -it -p 3306:3306/tcp gotocompany/shield:latest"

Usage

Shield is purely API-driven. It is very easy to get started with Shield. It provides CLI, HTTP and GRPC APIs for simpler developer experience.

CLI

Shield CLI is fully featured and simple to use, even for those who have very limited experience working from the command line. Run shield --help to see list of all available commands and instructions to use.

List of commands

shield --help

Print command reference

shield reference

API

Shield provides a fully-featured GRPC and HTTP API to interact with Shield server. Both APIs adheres to a set of standards that are rigidly followed. Please refer to proton for GRPC API definitions.

Running locally

Dependencies:

- Git
- Go 1.21 or above
- PostgreSQL 15 or above
  - pg_partman 4.7.4
  - pg_cron 1.6

Clone the repo

git clone [email protected]:goto/shield.git

Install all the golang dependencies

make install

Build shield binary file

make build

Init config

cp internal/server/config.yaml config.yaml
./shield config init

Run database migrations

Add these config in postgresql.conf

cron.database_name = {database name}
shared_preload_libraries = 'pg_cron'

./shield server migrate -c config.yaml

Start shield server

./shield server start -c config.yaml

Running tests

# Running all unit tests
$ make test

# Print code coverage
$ make coverage

Contribute

Development of Shield happens in the open on GitHub, and we are grateful to the community for contributing bugfixes and improvements. Read below to learn how you can take part in improving Shield.

Read our contributing guide to learn about our development process, how to propose bugfixes and improvements, and how to build and test your changes to Shield.

To help you get your feet wet and get you familiar with our contribution process, we have a list of good first issues that contain bugs which have a relatively limited scope. This is a great place to get started.

This project exists thanks to all the contributors.

License

Shield is Apache 2.0 licensed.

shield's Issues

Upgrade salt to fix time duration config

Describe the bug
Salt v0.3.0 has a bug where e cannot define time duration with ms or s and should always pass nanoseconds. This makes the config less readable.

We need to bump up salt version to fix this.

[Question] Why do we have policies & roles in shield?

Not a bug

This is a design question, why do we have policies & roles in Shield? This should be handled by spicedb and Shield can work only as a passthrough for it right? I feel we are trying to re-implement spicedb in Shield. For example, having our own yaml structure to define relations and permissions(resource_config) for spicedb. Which is not only more complicated, it is also restricting users from using spicedb UI to validate/visualize relations by https://play.authzed.com/ tool.

Bump go version to 1.21

Summary
Bumping go version to go 1.21 to keep up to date

• bumping workflow github action
• check all breaking dependencies & update them if needed

Return ErrBadRequest message with more relevant message

Describe the bug
The error 400 ErrBadRequest

shield/internal/api/v1beta1/errors.go

Line 14 in fc0e9e6

ErrBadRequest = errors.New("invalid syntax in body")

returns message "invalid syntax in body"

However it is not always the case for some API. The invalid syntax might be in query param. We need to update the name to be more relevant.

GetUser accept e-mail as identifier

Is your feature request related to a problem? Please describe.

• The GetUser API need to accept e-mail as its identifier.

Describe the solution you'd like
GetUser API could interchangeably use e-mail and UUID

Support group slug in resources definition

Is your feature request related to a problem? Please describe.
So far we only support ID for the resources definition. Our hook will create a new relation in the DB with UUID. There is a need to support Group slug as well in the resource creation.

Describe the solution you'd like
If Group slug is passed, we could transform the group slug to uuid before creating a new relation.

Check user API with explicit e-mail in URL

We have /check API that does check whether the caller has a permission or not, the caller identity is passed through the header.
We need an API that does check API but the identity is being passed explicitly through URL.