Introducing Entitlements: GitHub’s open source Identity and Access Management solution

We strongly believe in using GitHub to build GitHub, keeping the developer experience streamlined and integrating directly into their workflows. We track our work in Issues, plan work in projects, and automate reminders through GitHub Actions and ChatOps. So, it’s natural that we would look to GitOps to solve one of the more complex problems in IT security: Identity and Access Management (IAM). We wanted a solution that worked with our tools, was auditable, scalable, and well understood by developers. In this spirit, we built Entitlements, which uses a Git repository for the source-of-truth, declarative authorizations, and seamless integration with GitHub.com for approvals and audits. After years of development and countless contributions from GitHub employees, we are very excited to finally open source it!

Alleviating IAM pain points with Entitlements

Audits

Access requests and approvals are typically hard to track and audit. Without a scalable system in place, you may find yourself granting or requesting access that requires manual point-and-click actions. This makes it hard to track and prove audit controls. For instance, verifying appropriate approval and ensuring access revocation on termination or change of roles.

Entitlements leverages GitHub.com by storing its configuration in a repository and flowing all changes to those configurations through pull requests, so we have a durable audit trail of the request and its approvals.

Entitlements also supports metadata tags inside of the Entitlements configuration, which allows you to scan those configs and generate pull requests to audit and re-approve on a periodic basis. This supports enhanced auditing for your high risk configurations.

With expirations inside of the Entitlements configurations you can grant access to systems for an exact period of time with assurance that the access will be appropriately revoked after that time period.

Trust us—your auditors will love you.

Re-orgs

It is natural for organizations large and small to re-organize team structures to adapt to changing business demands. When re-orgs happen, it is common for access to accumulate, leaving you with access from both your old role and your new role. Entitlements can help prevent this.

At GitHub, we periodically pull a list of our employees from our internal source of truth and output that to various groups. We create automatic groups per manager, per region, per level, and per business function. By referencing these automatic groups wherever possible, we can ensure that access is added and revoked appropriately when business needs or organizations change.

Scalability

A team managing IAM requests for a large company can quickly become overwhelmed with the scale. That team also needs admin access on every tool and service at the company in order to fulfill these access requests.

At GitHub, Entitlements manages access to over 500 internal services, hundreds of GitHub.com organizations, and thousands of GitHub.com teams. Entitlements acts as a true force multiplier, allowing a fairly small team to manage large scale IAM.

Self-service

Since the Entitlements configurations are stored on GitHub.com, changes are self-service and not blocked by any specific team. Anyone can make a pull request adding themselves to an Entitlement configuration, get the appropriate approvals, and deploy their own pull request. This is full end-to-end self-service for IAM requests.

Entitlements on GitHub.com

While you can use Entitlements with any Git repository, leveraging it with GitHub.com unlocks its full potential.

Manager review

Leveraging GitHub.com with Entitlements can allow you to verify that each access change has an accompanying manager review.

By parsing the Entitlements diff, you can write a simple GitHub Action to parse the diff for affected users and request their manager’s review on the pull request.

You now have a full audit trail of the approval and deployment granting access.

Strictly audited Entitlements

GitHub.com can be used to enforce periodic reviews of Entitlements configurations which you deem to be high-risk.

You can write a simple cron job which checks each high-risk Entitlement configuration for a metadata tag, and parses the defined date. If that configuration contains a date which is older than the review time frame, a pull request can be created to re-approve the access.

This allows you to prove that access is re-approved appropriately, and the approval and justification are tracked in Git history.

You can further leverage expirations in Entitlements to automatically expire these high-risk Entitlements configurations if they are not re-approved.

Automatic updates from business data

You can write a simple cron job which checks a business data source-of-truth for updates and pushes those updates to the Entitlements org chart. Entitlements will re-organize the group membership based off of this new data and automatically handle de-provisioning old access and re-provisioning new access for each new role.

What next?

For more information on running Entitlements, stop by the Entitlements App repo where you’ll find more information on features and implementations.

For example configuration and some example workflows described above, visit the Entitlements Config repo.

We’ve also open sourced two Entitlements output plugins, entitlements-github-plugin and entitlements-gitrepo-auditor-plugin.

GitHub uses Entitlements every day, averaging around 2,000 commits per month. We’re constantly shipping improvements to the app and exploring ways to make it even easier to use. We want to enable others to use what we’ve built for their own IAM needs. We are excited to gather feedback and contributions from the community!

Thanks

This was truly a group effort! Thank you to all the people who devoted time and energy into building this internally—ultimately leading us to open sourcing the project and making it broadly available to developers and teams everywhere.

Huge shout-out to @DanHoerst, @kpaulisse, @missinformed, @jameswhite, @rick, @chrisgavin, @jar349, @kamarcum, @SIGUSRBACON, @hortoncd, @diver-gent, @cwage, @elopezacosta, @grantbirki, @hosom, @jamesooo, @jasonmacgowan, @nobe4, @northrup, and @shaeli.

Written by

Shawna Butterworth

@mrsbworth