This tutorial shows how you can use OPA and Linux-PAM to enforce fine-grained, host-level access controls over SSH and sudo.

Linux-PAM can be configured to delegate authorization decisions to plugins (shared libraries). In this case, we have created an OPA-based plugin that can be configured to authorize SSH and sudo access. The OPA-based Linux-PAM plugin used in this tutorial can be found at .

For this tutorial, our desired policy is:

  • Admins can SSH into any host and run sudo commands.
  • Normal users can SSH into hosts that they have contributed to and run sudo commands.

Furthermore, we’ll assume we have the following set of users and hosts:

  • frontend-dev is a developer who contributes to the app running on the frontend host.
  • backend-dev is a developer who contributes to the app running on the backend host.
  • ops is an administrator for the organization.

Authentication (verifying user identity) is outside the scope of OPA’s responsibility so this tutorial relies on identities being statically defined. In real-world scenarios authentication can be delegated to SSH itself (authorized_keys) or other identity management systems.

Let’s get started.

This tutorial requires Docker Compose to run dummy SSH hosts along with OPA. The dummy SSH hosts are just containers running sshd inside.

First, create a tutorial-docker-compose.yaml file that runs OPA and the containers that represent our backend and frontend hosts.

tutorial-docker-compose.yaml:

The tutorial-docker-compose.yaml file requires two other local files: frontend_host_id.json and backend_host_id.json. These files are mounted into the containers representing our hosts. The content of the file provides context that the PAM module provides as input when executing queries against OPA.

Create the extra files required by tutorial-docker-compose.yaml:

  1. echo '{"host_id": "frontend"}' > frontend_host_id.json
  2. echo '{"host_id": "backend"}' > backend_host_id.json

Finally, run docker-compose to pull and run the containers.

  1. docker-compose -f tutorial-docker-compose.yaml up

This tutorial uses a special Docker image named openpolicyagent/demo-pam to simulate an SSH server. This image contains pre-created Linux accounts for our users, and the required PAM module is pre-configured inside the sudo and sshd files in /etc/pam.d/.

In another terminal, load the policies and data into OPA that will control access to the hosts.

First, create a policy that will tell the PAM module to collect context that is required for authorization. For more details on what this policy should look like, see .

pull.rego:

  1. package pull
  3. # Which files should be loaded into the context?
  4. files = ["/etc/host_identity.json"]
  6. # Which environment variables should be loaded into the context?
  7. env_vars = []
  1. curl -X PUT --data-binary @pull.rego \
  2.   localhost:8181/v1/policies/pull

Next, create the policies that will authorize SSH and sudo requests. The input which makes up the authorization context in the policy below will also include some default values, such as the username making the request. See this documentation to get a better understanding of what the input to the authorization policy will look like.

Unlike the pull policy, we’ll create separate authz policies for SSH and sudo for more fine-grained control. In production, it makes more sense to have this separation for display and pull as well.

Create the SSH authorization policy. It should allow admins to SSH into all hosts, and non-admins to only SSH into hosts that they contributed code to.

sshd_authz.rego:

  1. package sshd.authz
  3. import input.pull_responses
  4. import input.sysinfo
  6. import data.hosts
  8. # By default, users are not authorized.
  9. default allow = false
  11. # Allow access to any user that has the "admin" role.
  12. allow {
  13.     data.roles["admin"][_] == input.sysinfo.pam_username
  14. }
  16. #
  17. # This rule gets the "host_id" value from the file "/etc/host_identity.json".
  18. # It is available in the input under "pull_responses" because we
  19. # asked for it in our pull policy above.
  20. #
  22. # that is asking for authorization.
  23. allow {
  24.     hosts[pull_responses.files["/etc/host_identity.json"].host_id].contributors[_] == sysinfo.pam_username
  25. }
  27. # If the user is not authorized, then include an error message in the response.
  28. errors["Request denied by administrative policy"] {
  29.     not allow
  30. }

Load this policy into OPA.

  1. curl -X PUT --data-binary @sshd_authz.rego \
  2.   localhost:8181/v1/policies/sshd/authz

Create the sudo authorization policy. It should allow only admins to use sudo.

sudo_authz.rego:

Load this policy into OPA.

  1. curl -X PUT --data-binary @sudo_authz.rego \
  2.   localhost:8181/v1/policies/sudo/authz

Finally, load the data that represents our roles and contributors into OPA.

  1. curl -X PUT localhost:8181/v1/data/roles -d \
  2. '{
  3.     "admin": ["ops"]
  4. }'
  1. curl -X PUT localhost:8181/v1/data/hosts -d \
  2. '{
  3.   "frontend": {
  4.     "contributors": [
  5.       "frontend-dev"
  6.     ]
  7.   },
  8.   "backend": {
  9.     "contributors": [
  10.       "backend-dev"
  11.     ]
  12.   }
  13. }'

First, let’s try to access the hosts as the ops user. Recall, the ops user has been granted the admin role (via the PUT /data/roles request above) and users with the admin role can login to any host and perform sudo commands.

Login to the frontend host (which has SSH listening on port 2222) and run a command with sudo as the ops user.

  1. ssh -p 2222 ops@localhost \
  2.   -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null
  4. sudo ls /

You will see a lot of verbose logs from sudo as the PAM module goes through the motions. This is intended so you can study how the PAM module works. You can disable verbose logging by changing the log_level argument in the PAM configuration. For more details see .

Let’s try a user without the admin role. Recall, that a non-admin user can SSH into any host that they have contributed to.

The frontend-dev user contributed code to the frontend host so they should be able to login.

  1. ssh -p 2222 frontend-dev@localhost \

Only admins can use sudo, so you shouldn’t be able to run sudo ls /.

Since frontend-dev did not contribute to the code running on the backend host (which has SSH listening on port 2223), they should not be able to login.

  1. ssh -p 2223 frontend-dev@localhost \
  2.   -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null

Suppose you have a ticketing system for elevation, where you generate tickets for users that need elevated rights, send the ticket to the user, and expire those tickets when their rights should be removed.

This means that for now, if the frontend-dev user can provide ticket number 1234, they should be able to SSH into all servers.

Let’s write policy to ensure that this happens.

First, we need to make the PAM module take input from the user.

display.rego:

  1. package display
  3. # What should be prompted to the user?
  4. display_spec = [
  5.   {
  6.     "message": "Please enter an elevation ticket if you have one:",
  7.     "style": "prompt_echo_on",
  8.     "key": "ticket"
  9.   }
  10. ]

Load this policy into OPA.

  1. curl -X PUT --data-binary @display.rego \
  2.   localhost:8181/v1/policies/display

Then we need to make sure that the authorization takes this input into account.

  1. # A package can be defined across multiple files.
  2. package sudo.authz
  4. import data.elevate
  5. import input.sysinfo
  6. import input.display_responses
  8. # Allow this user if the elevation ticket they provided matches our mock API
  9. # of an internal elevation system.
  10. allow {
  11.   elevate.tickets[sysinfo.pam_username] == display_responses.ticket
  12. }

Load this policy into OPA.

  1. curl -X PUT --data-binary @sudo_authz_elevated.rego \
  2.   localhost:8181/v1/policies/sudo_authz_elevated

Confirm that the user frontend-dev can indeed use sudo.

  1. ssh -p 2222 frontend-dev@localhost \
  2.   -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null
  4. sudo ls /

You should be prompted with the message that we defined in our display policy for both the SSH and sudo authorization cycles. This happens because the display policy is shared by the PAM configurations of SSH and sudo. In production, it is more practical to use separate policy packages for each PAM configuration.

We have not defined the SSH authz policy to work with elevation, so you can enter any value into the prompt that comes up for for SSH.

For sudo, enter the ticket number 1234 to get access.

Lastly, update the mocked elevation API and confirm the user’s original rights are restored.

  1. curl -X PUT localhost:8181/v1/data/elevate -d \
  2. '{
  3.   "tickets": {}
  4. }'

You will find that running sudo ls / as the frontend-dev user is disallowed again.

It is possible to configure the display policy to only make the PAM module prompt for the elevation ticket when our mock API has a non-empty tickets object. So when there are no elevated users, there will be no prompt for a ticket. This can be done using the Rego count aggregate.

Congratulations for finishing the tutorial!

You learned a number of things about SSH with OPA:

  • OPA gives you fine-grained access control over SSH, , and any other application that uses PAM. Although this tutorial used the some of the same policies for both SSH and sudo, you should use separate, fine-grained policies for each application that supports PAM.
  • Writing allow/deny policies to control who has access to what using context from the user and host.

The code for the PAM module used in this tutorial can be found in the repository.