cloud-identity-broker

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
• Vault
• Netbox
• GitHub Oauth Application
• SSL certificates
• 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
• 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