Conjur

Conjur provides secrets management and machine identity for modern infrastructure:

Machine Authorization Markup Language ("MAML"), a role-based access policy language to define system components & their roles, privileges and metadata
A REST web service to:
- manage identity life cycles for humans and machines
- organize and search roles and data in your secrets infrastructure
- authorize access to resources using a sophisticated permission model
- store secrets and make them available securely
Integrations throughout the cloud toolchain:
- infrastructure as a service (IaaS)
- configuration management
- continuous integration and deployment (CI/CD)
- container management and cloud orchestration

Note: our badges and social media buttons never track you.

Community Support

Our primary channel for support is through our Slack community. More here: community support

Development

We welcome contributions of all kinds to Conjur. See our contributing guide.

Prerequisites

Before getting started, you should install some developer tools. These are not required to deploy Conjur but they will let you develop using a standardized, expertly configured environment.

git to manage source code
Docker to manage dependencies and runtime environments
Docker Compose to orchestrate Docker environments

Build Conjur as a Docker image

It's easy to get started with Conjur and Docker:

install dependencies (as above)
clone this repository

run the build script in your terminal:

$ ./build.sh
...
Successfully built 9a18a1396977
$ docker images | grep conjur
conjurinc/conjur latest a8229592474c 7 minutes ago 560.7 MB
conjur           latest a8229592474c 7 minutes ago 560.7 MB
conjur-dev       latest af98cb5b2a68 4 days ago    639.9 MB

Set up a development environment

The dev directory contains a docker-compose file which creates a development environment with a database container (pg, short for postgres), and a conjur server container with source code mounted into the directory /src/conjur.

To use it:

install dependencies (as above)
build the Conjur image:
```
$ ./build.sh
```
start the container:
```
$ cd dev
$ ./start.sh
...
root@f39015718062:/src/conjur#
```
Once the start.sh script finishes, you're in a Bash shell in the Conjur server container.
run the server
```
root@f39015718062:/src/conjur# conjurctl server
<various startup messages, then finally:>
* Listening on tcp://localhost:3000
Use Ctrl-C to stop
```
The conjurctl server script performs the following:
- wait for the database to be available
- create and/or upgrade the database schema according to the db/migrate directory
- find or create the token-signing key
- start the web server

Testing

Conjur has rspec and cucumber tests.

RSpec

RSpec tests are easy to run from within the conjur server container:

root@aa8bc35ba7f4:/src/conjur# rspec
Run options: exclude {:performance=>true}

Randomized with seed 62317
.............................................

Finished in 3.84 seconds (files took 3.33 seconds to load)
45 examples, 0 failures

Cucumber

Cucumber tests require the Conjur server to be running. It's easiest to achieve this by starting Conjur in one container and running Cucumber from another. Run the service in the conjur server container:

root@aa8bc35ba7f4:/src/conjur# conjurctl server
...
* Listening on tcp://localhost:3000
Use Ctrl-C to stop

Then start a second container to run the cukes:

$ ./cucumber.sh
...
root@9feae5e5e001:/src/conjur#

There are two cucumber suites: api and policy. They are located in subdirectories of ./cucumber.

Run all the cukes:

root@9feae5e5e001:/src/conjur# cd cucumber/api
root@9feae5e5e001:/src/conjur/cucumber/api# cucumber
...
27 scenarios (27 passed)
101 steps (101 passed)
0m4.404s

Run just one feature:

root@9feae5e5e001:/src/conjur# cucumber -r cucumber/api/features/support -r cucumber/api/features/step_definitions cucumber/api/features/resource_list.feature

Documentation site

This repository also contains the entire source code for the Conjur documentation website. For instructions on how to work on the site locally, visit the docs README.

Or in brief:

$ docker-compose run --rm apidocs > docs/_includes/api.html
$ docker-compose up -d docs
$ open localhost:4000

Architecture

Conjur is designed to run in a Docker container(s), using Postgresql as the backing data store. It's easy to run both Conjur and Postgresql in Docker; see the demo directory for an example.

Database

DATABASE_URL environment variable

Conjur uses the DATABASE_URL environment variable to connect to the database. Typical options for this URL are:

Local linked pg container
External managed database such as AWS RDS.

Database initialization

Conjur creates and/or updates the database schema automatically when it starts up. Migration scripts are located in the db/migrate directory.

Secrets and keys

Main article: Conjur Cryptography

Conjur uses industry-standard cryptography to protect your data.

Some operations require storage and management of encrypted data. For example:

Roles can have associated API keys, which are stored encrypted in the database
the authenticate function issues a signed JSON token; the signing key is a 2048 bit RSA key which is stored encrypted in the database

Data is encrypted in and out of the database using Slosilo, a library which provides:

symmetric encryption using AES-256-GCM
a Ruby class mixin for easy encryption of object attributes into the database
asymmetric encryption and signing
a keystore in a Postgresql database for easy storage and retrieval of keys

Slosilo has been verified by a professional cryptographic audit. Ask in our Slack community for more details. (You can join here.)

Important: avoid data loss

When you start Conjur, you must provide a Base64-encoded master data key in the environment variable CONJUR_DATA_KEY. You can generate a data key using the following command:

$ docker run --rm conjur data-key generate

Do NOT lose the data key, or all the encrypted data will be unrecoverable.

Account management

Conjur supports the simultaneous operation of multiple separate accounts within the same database. In other words, it's multi-tenant.

Each account (also called "organization account") has its own token-signing private key. When a role is authenticated, the HMAC of the access token is computed using the signing key of the role's account.

Accounts can be listed, created, and deleted via the /accounts service. Permission to use this service is controlled by the built-in resource !:webservice:accounts. Note that ! is itself an organization account, and therefore privileges on the !:webservice:accounts can be managed via Conjur policies.

Licensing

The Conjur server (as in, the code within this repository) is licensed under the Free Software Foundation's GNU AGPL v3.0. This license was chosen to ensure that all contributions to the Conjur server are made available to the community. Commercial licenses are also available from CyberArk.

The Conjur API clients and other extensions are licensed under the Apache Software License v2.0

wilkhu90 / conjur Goto Github PK

conjur's Introduction