Tutorial: Using Cerbos with AWS Cognito

This documentation is for a previous version of Cerbos. Choose 0.40.0 from the version picker at the top right or navigate to https://docs.cerbos.dev for the latest version.

An example application of integrating Cerbos with a FastAPI server using AWS Cognito for authentication.

Demo Video

Dependencies

Python 3.10
Docker for running the Cerbos Policy Decision Point (PDP)
A configured AWS Cognito User Pool (set-up guide)

Getting Started

Clone the repo

git clone git@github.com:cerbos/python-cognito-cerbos.git

Start up the Cerbos PDP instance docker container. This will be called by the FastAPI app to check authorization.
```
cd cerbos
./start.sh
```
Install python dependencies
```
# from project root
./pw install
```

Set the appropriate environment variables

AWS_COGNITO_POOL_ID
AWS_COGNITO_CLIENT_ID
AWS_DEFAULT_REGION
AWS_COGNITO_POOL_NAME

# if you've configured your user pool with a client secret
AWS_COGNITO_CLIENT_SECRET

# optionally, to enable the hosted UI:
AWS_COGNITO_HOSTED_UI_CALLBACK_URL # this needs to match the callback URL configured for the hosted UI
AWS_COGNITO_HOSTED_UI_LOGOUT_URL

Start the FastAPI dev server
```
./pw demo
```

Cognito Configuration

Groups

This demo maps Cognito User Pool groups to Cerbos roles. The app will retrieve the groups from the access token, and use them to determine authorization.

Any test users in your pool should be added to one or both of admin and/or user groups to demonstrate different access to the demo resources.

Policies

This example has a simple CRUD policy in place for a resource kind of contact - like a CRM system would have. The policy file can be found in the cerbos/policies folder here.

Should you wish to experiment with this policy, you can try it in the Cerbos Playground.

The policy expects one of two roles to be set on the principal - admin and user. These roles are authorized as follows:

Action	User	Admin
list	Y	Y
read	Y	Y
create	Y	Y
update	If owner	Y
delete	If owner	Y

Action

User

Admin

list

read

create

update

If owner

delete

If owner

This business logic is represented in Cerbos as a resource policy.

---
apiVersion: api.cerbos.dev/v1
resourcePolicy:
  version: default
  resource: contact
  rules:
    - actions: ["read", "create"]
      effect: EFFECT_ALLOW
      roles:
        - admin
        - user

    - actions: ["update", "delete"]
      effect: EFFECT_ALLOW
      roles:
        - admin

    - actions: ["update", "delete"]
      effect: EFFECT_ALLOW
      roles:
        - user
      condition:
        match:
          expr: request.resource.attr.owner == request.principal.id