# Cloud Identity Broker This is a cloud identity broker. Identity brokers exist to bridge authentication from one system into authentication to another system. In the case of this broker it bridges GitHub and GitLab authentication into temporary credentials for cloud providers. The broker has an interactive API that can be used in a web browser as well as a JSON/REST API that can be consumed programmatically. The reason this broker exists is to provide one secured location for long-lived cloud provider credentials that can be easily consumed from development environments and build systems while limiting the scope of access and time frame of access those systems have to cloud resources. This helps to increase the security of those accounts and reduce the risk of abuse. All access through the broker is chained to an authenticated and authorized user account and all access through those user accounts are logged for auditing. All credentials returned by the broker have a strict time limit after which they are useless. This broker started life as a piece of internal infrastructure specific to AWS that has been re-written and open sourced with the goal to support multiple clouds. For documentation the REST API look at the `README_BROKER.md` file. ## Contributing Contributions are welcomed. Please send contributions to mike-at-crute-dot-us either through email in `git format-patch` format or send a link to a git repo and branch name that the author can pull and merge. If you're reading this on one of the author's git forge accounts (GitHub, GitLab, sr.ht, etc...) feel free to open a pull/merge request with your changes. The author reserves the right to request changes to contributions before merging them or to not merge them at all but will endeavour to be reasonable in those requests. ## Building This requires Go 1.17 or newer to build. Provided that a simple `make` should create a `cloud-identity-broker` binary that's ready to use. The built binary embeds all of the templates in production mode and will require nothing more than the binary itself to run, if running in `--debug` mode then the `templates` folder must be available. ## Running It's complicated, so probably don't? The application requires some bits of infrastructure to be in place for it to run but then can be exposed directly to the internet or put behind a reverse proxy. You will need: - [Mongodb](https://www.mongodb.com/) - [Vault](https://www.hashicorp.com/products/vault) - [Netbox](https://netbox.dev/) - [GitHub Oauth Application](https://docs.github.com/en/developers/apps/building-oauth-apps/creating-an-oauth-app) - [SSL certificates](https://letsencrypt.org/) - Internal DNS Service (for LetsEncrypt DNS challenges) Once the requisite infrastructure (see below) is configured, run the binary like so: ``` VAULT_ROLE_ID="..." \ VAULT_SECRET_ID="..." \ VAULT_ADDR="https://your-vault-addr:8200" \ ./cloud-identity-broker \ --mongodb-uri="your-vault-path@your-mongodb-host/your-db-name" \ --github-oauth-vault-path="service/service-name/github-oauth" \ web ``` ### SSL Certificates SSL certificates of a cipher type compatible with Go's SSL library are required to run the binary, even in development mode. Obtain those certificates however you would normal do so. Both a key and certificate are required to be stored in the directory identified by `--tls-cache-dir` (which defaults to `./ssl/`). Both files should be of PEM format with the certificate named `cert.pem` and the key named `key.pem`. ### Vault Setup Configure Vault per the manufacturers instructions. Create an AppRole for the identity broker and provide the credentials to the binary using the standard Vault environment variables. The binary will need access to a set of GitHub Oauth client credentials for a GitHub Oauth application that is used to authenticate users to the broker. Setup an application on GitHub and store the client ID and client secret in a JSON document in Vault the vault KV backend with the following format: ``` { "client-id": "your client id", "client-secret": "your client secret" } ``` Provide the path to this material with the `--github-oauth-vault-path` command line argument. You should omit the `kv/data/` prefix to the path. For each AWS cloud account to which the broker provides access a JSON document must be stored in the Vault KV backend. The format of this document is as follows. The path to this document is provided (with the `kv/data/` prefix omitted) in the `VaultMaterial` field of the `Account` record for the account in Mongodb. ``` { "AccessKeyId": "...", "SecretAccessKey": "...", "Roles": { "account-short-name": { "ARN": "arn:aws:iam::...:role/...", "ExternalId": "..." } } } ``` The fields are: - `AccessKeyId` which is the access key ID of an IAM user that can assume roles in the target account. - `SecretAccessKey` is the secret key for the IAM user identified by the access key ID. - `Roles` is a mapping of account `ShortName` to an AWS ARN and ExternalId used for assuming roles. The `ARN` is the role to be assumed and the `ExternalId` is the External ID configured in the role trust policy. Note that this application does **not** use the AWS Vault backend to assume roles due to limitations AWS places on roles assumed using assumed role credentials and not user credentials. Finally the broker will need access to a Mongodb credential. Currently this requires a static credential but in the future a dynamic credential will be acceptable. Create this credential and pass it in the `--mongodb-vault-path` argument. It should have the form `database/static-creds/your-cred-name`. ### Mongodb Setup The application needs a Mongodb database with at least a `users` collection created. The rest are optional. To create the `users` collection insert a record to the collection that contains your GitHub username as the `_id` field and has `IsAdmin` set to true. For example: ``` db.users.insert({ "_id": "mcrute", "IsAdmin": true }) ``` This is adequate to allow login via GitHub for the named user. All other fields will be populated automatically by the app. To create allowed AWS accounts for use in the broker add them to the `accounts` collection. Those records have the following form: ``` { "_id": "acocunt-short-name", "AccountNumber": 12345, "AccountType": "aws", "ConsoleSessionDuration": 21600000000000, "DefaultRegion": "us-west-2", "Name": "Some Description", "Users": [ "username1", "username2" ], "VaultMaterial": "some/path/as/above" } ``` - `_id` is the short name of the account. This must also map into a Vault material per above. - `AccountNumber` is the AWS account number for the account being brokered. - `AccountType` is the string `aws` for now - `ConsoleSessionDuration` is the number of nanoseconds a console session can exist before timing out. (Nanoseconds are silly, yes; it's a serialized time.Time) - `DefaultRegion` is the region considered default, this is just used as an indicator in the JSON API. - `Name` a longer form, descriptive name of the account. - `Users` a case-sensitive list of GitHub user names that have access to this account - `VaultMaterial` the path to the Vault material that contains the account credentials document, as above. ## Notes on Infrastructure The infrastructural decisions of the project were made based on the systems readily available to the original author and their production readiness. The code itself has been structured to avoid forcing those decisions on future users. Everything is coded to generic models and interfaces for database and secret access. With a little additional code it should be possible to swap in preferred implementations for both of those systems. The project is happy to entertain alternative back-ends for these interfaces. ## To Do - Allow GitLab CI jobs to auth using [job tokens](https://docs.gitlab.com/ee/api/jobs.html#get-job-tokens-job) - Implement an Admin UI, all admin ops are directly on the DB at the moment - Remove internal service dependencies - Support dynamic mongodb credentials - Support for other clouds - GCP - OCI - Azure ## Contributors - [Mike Crute](https://mike.crute.us)