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.
Our primary channel for support is through our Slack community. More here: community support
Migrating data from Conjur Open Source to Conjur EE is simple using our migration guide
We welcome contributions of all kinds to Conjur. See our contributing guide.
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
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
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-server
.
To use it:
-
Install dependencies (as above)
-
Start the container (and optional extensions):
$ cd dev $ ./start ... root@f39015718062:/src/conjur-server#
Once the
start
script finishes, you're in a Bash shell inside the Conjur server container. ToAfter staring Conjur, your instance will be configured with the following:
- Account:
cucumber
- User:
admin
- Password: Run
conjurctl role retrieve-key cucumber:user:admin
inside the container shell to retrieve the admin user API key (which is also the password)
- Account:
-
Run the server
root@f39015718062:/src/conjur-server# 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
If you are going to be debugging Conjur using
pry.byebug
, you may choose to start the web server by callingrails server -b 0.0.0.0 webrick
instead ofconjurctl server
. This will allow you to work in the debugger without the server timing out. -
Cleanup
$ ./stop
Running
stop
removes the running Docker Compose containers and the data key.
To enable a user to log into Conjur using LDAP credentials, run start
with the --authn-ldap
flag:
$ cd dev
$ ./start --authn-ldap
...
root@f39015718062:/src/conjur-server#
The --authn-ldap
flag will:
- Start an OpenLDAP container.
- Load a user
alice
with the passwordalice
into the LDAP server. - Load a policy
authn-ldap/test
, that grantsalice
the ability to authenticate viahttp://localhost:3000/authn-ldap/test/cucumber/alice/authenticate
with the passwordalice
.
Validate authentication using the username alice
with the password alice
:
$ curl -v -k -X POST -d "alice" http://localhost:3000/authn-ldap/test/cucumber/alice/authenticate
As a developer, there are a number of common scenarios when actively working on Conjur.
The ./cli
script, located in the dev
folder is intended to streamline these tasks.
$ ./cli --help
NAME
cli - Development tool to simplify working with a Conjur container.
SYNOPSIS
cli [global options] command [command options] [arguments...]
GLOBAL OPTIONS
--help - Show this message
COMMANDS
exec - Steps into the running Conjur container, into a bash shell.
key - Displays the admin user API key
policy load <account> <policy/path.yml> - Loads a conjur policy into the provided account.
$ ./cli exec
root@88d43f7b3dfa:/src/conjur-server#
$ ./cli key
3xmx4tn353q4m02f8e0xc1spj8zt6qpmwv178f5z83g6b101eepwn1
$ ./cli policy load <account> <policy/path/from/project/root.yml>
For most development work, the account will be cucumber
, which is created when the development environment starts. The policy path must be inside the cyberark/conjur
project folder, and referenced from the project root.
Conjur has rspec
and cucumber
tests.
RSpec tests are easy to run from within the conjur
server container:
root@aa8bc35ba7f4:/src/conjur-server# 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 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-server# conjurctl server
...
* Listening on tcp://localhost:3000
Use Ctrl-C to stop
Then, using the dev/cli
script, step into the Conjur container to run the cukes:
$ ./cli exec
...
root@9feae5e5e001:/src/conjur-server#
There are three different cucumber suites: api
, policy
, and authenticators
. Each of these can be run using a profile of the same name:
root@9feae5e5e001:/src/conjur-server# cucumber --profile api # runs api cukes
root@9feae5e5e001:/src/conjur-server# cucumber --profile policy # runs policy cukes
root@9feae5e5e001:/src/conjur-server# cucumber --profile authenticators # runs authenticators cukes
root@9feae5e5e001:/src/conjur-server# cucumber --profile api cucumber/api/features/resource_list.feature
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.
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.
Conjur creates and/or updates the database schema automatically when it starts
up. Migration scripts are located in the db/migrate
directory.
Conjur makes it easy to:
- Enable and disable built-in authenticators
- Secure access to authenticators using policy files
- Create custom authenticators
Detailed authenticator documenation
Conjur makes it easy to:
- Rotate variables regularly using built-in rotators
- Create custom rotators
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.)
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.
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.
Starting from version 0.1.0, this project follows Semantic Versioning.
The changelog file is maintained based on Keep a Changelog guidelines.
Each accepted change to the Conjur code (documentation and website updates
excepted) requires adding a changelog entry to the corresponding Added
,
Changed
, Deprecated
, Removed
, Fixed
and/or Security
sub-section (add
one as necessary) of the Unreleased section in the changelog.
Bumping the version number after each and every change is not required, advised nor expected. Valid reasons to bump the version are for example:
- enough changes have accumulated,
- an important feature has been implemented,
- an external project depends on one of the recent changes.
-
Examine the changelog and decide on the version bump rank (major, minor, patch).
-
Change the title of Unreleased section of the changelog to the target version.
- Be sure to add the date (ISO 8601 format) to the section header.
-
Add a new, empty Unreleased section to the changelog.
- Remember to update the references at the bottom of the document.
-
Change VERSION file to reflect the change. This file is used by some scripts.
-
Commit these changes.
Bump version to x.y.z
is an acceptable commit message. -
Tag the version using eg.
git tag -s v0.1.1
. Note this requires you to be able to sign releases. Consult the github documentation on signing commits on how to set this up.-
git will ask you to enter the tag message. These will become the release notes. Format should be like this (note the subject line and message):
Version x.y.z This is a human-readable overview of the changes in x.y.z. It should be a consise, at-a-glance summary. It certainly isn't a direct copy-and-paste from the changelog.
-
-
Push the tag:
git push vx.y.z
(orgit push origin vx.y.z
if you are working from your local machine). -
Create a pull request to have the release acked and merged.
Deleting and changing tags should be avoided. If in any doubt if the release will
be accepted, before creating a tag push the (VERSION and CHANGELOG) changes in
a branch and ask for approval. Then create and push a tag on master
once it's
been merged.
The Conjur server (as in, the code within this repository) is licensed under the Free Software Foundation's GNU LGPL 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