Lemur¶

Dependencies¶

Some basic prerequisites which you’ll need in order to run Lemur:

• A UNIX-based operating system (we test on Ubuntu, develop on OS X)
• Python 3.5 or greater
• PostgreSQL 9.4 or greater
• Nginx

Installing Build Dependencies¶

If installing Lemur on a bare Ubuntu OS you will need to grab the following packages so that Lemur can correctly build it’s dependencies:

$ sudo apt-get update
$ sudo apt-get install nodejs-legacy python-pip python-dev python3-dev libpq-dev build-essential libssl-dev libffi-dev nginx git supervisor npm postgresql

Now, install Python virtualenv package:

$ sudo pip install -U virtualenv

Setting up an Environment¶

In this guide, Lemur will be installed in /www, so you need to create that structure first:

$ sudo mkdir /www
$ cd /www

Clone Lemur inside the just created directory and give yourself write permission (we assume lemur is the user):

$ sudo useradd lemur
$ sudo passwd lemur
$ sudo mkdir /home/lemur
$ sudo chown lemur:lemur /home/lemur
$ sudo git clone https://github.com/Netflix/lemur
$ sudo chown -R lemur lemur/

Create the virtual environment, activate it and enter the Lemur’s directory:

$ su lemur
$ virtualenv -p python3 lemur
$ source /www/lemur/bin/activate
$ cd lemur

$ which python

$ make release

Example:
  urlContextPath=lemur
  /api/1/auth/providers -> /lemur/api/1/auth/providers

$ make release urlContextPath={desired context path}

Creating a configuration¶

Before we run Lemur, we must create a valid configuration file for it. The Lemur command line interface comes with a simple command to get you up and running quickly.

Simply run:

$ lemur create_config

You can specify -c or --config to any Lemur command to specify the current environment you are working in. Lemur will also look under the environmental variable LEMUR_CONF should that be easier to setup in your environment.

Update your configuration¶

Once created, you will need to update the configuration file with information about your environment, such as which database to talk to, where keys are stored etc.

$ vi ~/.lemur/lemur.conf.py

Before Lemur will run you need to fill in a few required variables in the configuration file:

LEMUR_SECURITY_TEAM_EMAIL
#/the e-mail address needs to be enclosed in quotes
LEMUR_DEFAULT_COUNTRY
LEMUR_DEFAULT_STATE
LEMUR_DEFAULT_LOCATION
LEMUR_DEFAUTL_ORGANIZATION
LEMUR_DEFAULT_ORGANIZATIONAL_UNIT

Setup Postgres¶

For production, a dedicated database is recommended, for this guide we will assume postgres has been installed and is on the same machine that Lemur is installed on.

First, set a password for the postgres user. For this guide, we will use lemur as an example but you should use the database password generated by Lemur:

$ sudo -u postgres -i
# \password postgres
Enter new password: lemur
Enter it again: lemur

Once successful, type CTRL-D to exit the Postgres shell.

Next, we will create our new database:

$ sudo -u postgres createdb lemur

Initializing Lemur¶

Lemur provides a helpful command that will initialize your database for you. It creates a default user (lemur) that is used by Lemur to help associate certificates that do not currently have an owner. This is most commonly the case when Lemur has discovered certificates from a third party source. This is also a default user that can be used to administer Lemur.

In addition to creating a new user, Lemur also creates a few default email notifications. These notifications are based on a few configuration options such as LEMUR_SECURITY_TEAM_EMAIL. They basically guarantee that every certificate within Lemur will send one expiration notification to the security team.

Additional notifications can be created through the UI or API. See Creating Notifications and Command Line Interface for details.

Make note of the password used as this will be used during first login to the Lemur UI.

$ cd /www/lemur/lemur
$ lemur init

Setup a Reverse Proxy¶

By default, Lemur runs on port 8000. Even if you change this, under normal conditions you won’t be able to bind to port 80. To get around this (and to avoid running Lemur as a privileged user, which you shouldn’t), we need setup a simple web proxy. There are many different web servers you can use for this, we like and recommend Nginx.

location /api {
     proxy_pass  http://127.0.0.1:8000;
     proxy_next_upstream error timeout invalid_header http_500 http_502 http_503 http_504;
     proxy_redirect off;
     proxy_buffering off;
     proxy_set_header        Host            $host;
     proxy_set_header        X-Real-IP       $remote_addr;
     proxy_set_header        X-Forwarded-For $proxy_add_x_forwarded_for;
 }

 location / {
     root /www/lemur/lemur/static/dist;
     include mime.types;
     index index.html;
 }

$ sudo service nginx restart

Starting the Web Service¶

Lemur provides a built-in web server (powered by gunicorn and eventlet) to get you off the ground quickly.

To start the web server, you simply use lemur start. If you opted to use an alternative configuration path you can pass that via the --config option.

# Lemur's server runs on port 8000 by default. Make sure your client reflects
# the correct host and port!
lemur --config=/etc/lemur.conf.py start -b 127.0.0.1:8000

You should now be able to test the web service by visiting http://localhost:8000/.

Running Lemur as a Service¶

We recommend using whatever software you are most familiar with for managing Lemur processes. One option is Supervisor.

[program:lemur-web]
directory=/www/lemur/
command=/www/lemur/bin/lemur start
autostart=true
autorestart=true
redirect_stderr=true
stdout_logfile syslog
stderr_logfile syslog

Syncing¶

Lemur uses periodic sync tasks to make sure it is up-to-date with its environment. Things change outside of Lemur we do our best to reconcile those changes. The recommended method is to use CRON:

$ crontab -e
*/15 * * * * lemur sync -s all
0 22 * * * lemur check_revoked
0 22 * * * lemur notify

Additional Utilities¶

If you’re familiar with Python you’ll quickly find yourself at home, and even more so if you’ve used Flask. The lemur command is just a simple wrapper around Flask’s manage.py, which means you get all of the power and flexibility that goes with it.

Some of the features which you’ll likely find useful are listed below.

What’s Next?¶

Get familiar with how Lemur works by reviewing the User Guide. When you’re ready see Production for more details on how to configure Lemur for production.

The above just gets you going, but for production there are several different security considerations to take into account. Remember, Lemur is handling sensitive data and security is imperative.

Basics¶

Because of the sensitivity of the information stored and maintained by Lemur it is important that you follow standard host hardening practices:

• Run Lemur with a limited user
• Disabled any unneeded services
• Enable remote logging
• Restrict access to host

TLS/SSL¶

server_tokens off;
add_header X-Frame-Options DENY;
add_header X-Content-Type-Options nosniff;
add_header X-XSS-Protection "1; mode=block";

server {
  listen       80;
  return       301 https://$host$request_uri;
}

server {
   listen      443;
   access_log  /var/log/nginx/log/lemur.access.log;
   error_log   /var/log/nginx/log/lemur.error.log;

   location /api {
        proxy_pass  http://127.0.0.1:8000;
        proxy_next_upstream error timeout invalid_header http_500 http_502 http_503 http_504;
        proxy_redirect off;
        proxy_buffering off;
        proxy_set_header        Host            $host;
        proxy_set_header        X-Real-IP       $remote_addr;
        proxy_set_header        X-Forwarded-For $proxy_add_x_forwarded_for;
    }

    location / {
        root /path/to/lemur/static/dist;
        include mime.types;
        index index.html;
    }


}

server_tokens off;
add_header X-Frame-Options DENY;
add_header X-Content-Type-Options nosniff;
add_header X-XSS-Protection "1; mode=block";

server {
  listen       80;
  return       301 https://$host$request_uri;
}

server {
   listen      443;
   access_log  /var/log/nginx/log/lemur.access.log;
   error_log   /var/log/nginx/log/lemur.error.log;

   # certs sent to the client in SERVER HELLO are concatenated in ssl_certificate
   ssl_certificate /path/to/signed_cert_plus_intermediates;
   ssl_certificate_key /path/to/private_key;
   ssl_session_timeout 1d;
   ssl_session_cache shared:SSL:50m;

   # Diffie-Hellman parameter for DHE ciphersuites, recommended 2048 bits
   ssl_dhparam /path/to/dhparam.pem;

   # modern configuration. tweak to your needs.
   ssl_protocols TLSv1.1 TLSv1.2;
   ssl_ciphers 'ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES256-GCM-SHA384:DHE-RSA-AES128-GCM-SHA256:DHE-DSS-AES128-GCM-SHA256:kEDH+AESGCM:ECDHE-RSA-AES128-SHA256:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA:ECDHE-ECDSA-AES128-SHA:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA:ECDHE-ECDSA-AES256-SHA:DHE-RSA-AES128-SHA256:DHE-RSA-AES128-SHA:DHE-DSS-AES128-SHA256:DHE-RSA-AES256-SHA256:DHE-DSS-AES256-SHA:DHE-RSA-AES256-SHA:!aNULL:!eNULL:!EXPORT:!DES:!RC4:!3DES:!MD5:!PSK';
   ssl_prefer_server_ciphers on;

   # HSTS (ngx_http_headers_module is required) (15768000 seconds = 6 months)
   add_header Strict-Transport-Security max-age=15768000;

   # OCSP Stapling ---
   # fetch OCSP records from URL in ssl_certificate and cache them
   ssl_stapling on;
   ssl_stapling_verify on;

   ## verify chain of trust of OCSP response using Root CA and Intermediate certs
   ssl_trusted_certificate /path/to/root_CA_cert_plus_intermediates;

   resolver <IP DNS resolver>;

   location /api {
        proxy_pass  http://127.0.0.1:8000;
        proxy_next_upstream error timeout invalid_header http_500 http_502 http_503 http_504;
        proxy_redirect off;
        proxy_buffering off;
        proxy_set_header        Host            $host;
        proxy_set_header        X-Real-IP       $remote_addr;
        proxy_set_header        X-Forwarded-For $proxy_add_x_forwarded_for;
    }

    location / {
        root /path/to/lemur/static/dist;
        include mime.types;
        index index.html;
    }


}

<VirtualHost *:443>
    ...
    SSLEngine on
    SSLCertificateFile      /path/to/signed_certificate
    SSLCertificateChainFile /path/to/intermediate_certificate
    SSLCertificateKeyFile   /path/to/private/key
    SSLCACertificateFile    /path/to/all_ca_certs

    # intermediate configuration, tweak to your needs
    SSLProtocol             all -SSLv2 -SSLv3
    SSLCipherSuite          ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES256-GCM-SHA384:DHE-RSA-AES128-GCM-SHA256:DHE-DSS-AES128-GCM-SHA256:kEDH+AESGCM:ECDHE-RSA-AES128-SHA256:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA:ECDHE-ECDSA-AES128-SHA:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA:ECDHE-ECDSA-AES256-SHA:DHE-RSA-AES128-SHA256:DHE-RSA-AES128-SHA:DHE-DSS-AES128-SHA256:DHE-RSA-AES256-SHA256:DHE-DSS-AES256-SHA:DHE-RSA-AES256-SHA:AES128-GCM-SHA256:AES256-GCM-SHA384:AES128-SHA256:AES256-SHA256:AES128-SHA:AES256-SHA:AES:CAMELLIA:DES-CBC3-SHA:!aNULL:!eNULL:!EXPORT:!DES:!RC4:!MD5:!PSK:!aECDH:!EDH-DSS-DES-CBC3-SHA:!EDH-RSA-DES-CBC3-SHA:!KRB5-DES-CBC3-SHA
    SSLHonorCipherOrder     on

    # HSTS (mod_headers is required) (15768000 seconds = 6 months)
    Header always set Strict-Transport-Security "max-age=15768000"
    ...
</VirtualHost>

Supervisor¶

Supervisor is a very nice way to manage you Python processes. We won’t cover the setup (which is just apt-get install supervisor or pip install supervisor most of the time), but here is a quick overview on how to use it.

Create a configuration file named supervisor.ini:

[unix_http_server]
file=/tmp/supervisor.sock

[supervisorctl]
serverurl=unix:///tmp/supervisor.sock

[rpcinterface:supervisor]
supervisor.rpcinterface_factory=supervisor.rpcinterface:make_main_rpcinterface

[supervisord]
logfile=/tmp/lemur.log
logfile_maxbytes=50MB
logfile_backups=2
loglevel=trace
pidfile=/tmp/supervisord.pid
nodaemon=false
minfds=1024
minprocs=200

[program:lemur]
command=python /path/to/lemur/manage.py manage.py start

directory=/path/to/lemur/
environment=PYTHONPATH='/path/to/lemur/',LEMUR_CONF='/home/lemur/.lemur/lemur.conf.py'
user=lemur
autostart=true
autorestart=true

The 4 first entries are just boiler plate to get you started, you can copy them verbatim.

The last one defines one (you can have many) process supervisor should manage.

It means it will run the command:

python manage.py start

In the directory, with the environment and the user you defined.

This command will be ran as a daemon, in the background.

autostart and autorestart just make it fire and forget: the site will always be running, even it crashes temporarily or if you restart the machine.

The first time you run supervisor, pass it the configuration file:

supervisord -c /path/to/supervisor.ini

Then you can manage the process by running:

supervisorctl -c /path/to/supervisor.ini

It will start a shell from which you can start/stop/restart the service.

You can read all errors that might occur from /tmp/lemur.log.

Periodic Tasks¶

Lemur contains a few tasks that are run and scheduled basis, currently the recommend way to run these tasks is to create a cron job that runs the commands.

There are currently three commands that could/should be run on a periodic basis:

• notify
• check_revoked
• sync

How often you run these commands is largely up to the user. notify and check_revoked are typically run at least once a day. sync is typically run every 15 minutes.

Example cron entries:

0 22 * * * lemuruser export LEMUR_CONF=/Users/me/.lemur/lemur.conf.py; /www/lemur/bin/lemur notify
*/15 * * * * lemuruser export LEMUR_CONF=/Users/me/.lemur/lemur.conf.py; /www/lemur/bin/lemur sync -s all
0 22 * * * lemuruser export LEMUR_CONF=/Users/me/.lemur/lemur.conf.py; /www/lemur/bin/lemur check_revoked

Create a New Authority¶

Before Lemur can issue certificates you must configure the authority you wish use. Lemur itself does not issue certificates, it relies on external CAs and the plugins associated with those CAs to create the certificate that Lemur can then manage.

In the authority table select “Create”

Enter an authority name and short description about the authority. Enter an owner, and certificate common name. Depending on the authority and the authority/issuer plugin these values may or may not be used.

Again how many of these values get used largely depends on the underlying plugin. It is important to make sure you select the right plugin that you wish to use.

Create a New Certificate¶

In the certificate table select “Create”

Enter an owner, short description and the authority you wish to issue this certificate. Enter a common name into the certificate, if no validity range is selected two years is the default.

You can add notification options and upload the created certificate to a destination, both of these are editable features and can be changed after the certificate has been created.

These options are typically for advanced users, the one exception is the Subject Alternate Names or SAN. For certificates that need to include more than one domains, the first domain is the Common Name and all other domains are added here as DNSName entries.

Import an Existing Certificate¶

Enter an owner, short description and public certificate. If there are intermediates and private keys Lemur will track them just as it does if the certificate were created through Lemur. Lemur generates a certificate name but you can override that by passing a value to the Custom Name field.

You can add notification options and upload the created certificate to a destination, both of these are editable features and can be changed after the certificate has been created.

Create a New User¶

From the settings dropdown select “Users”

In the user table select “Create”

Enter the username, email and password for the user. You can also assign any roles that the user will need when they login. While there is no deletion (we want to track creators forever) you can mark a user as ‘Inactive’ that will not allow them to login to Lemur.

Create a New Role¶

From the settings dropdown select “Roles”

In the role table select “Create”

Enter a role name and short description about the role. You can optionally store a user/password on the role. This is useful if your authority require specific roles. You can then accurately map those roles onto Lemur users. Also optional you can assign users to your new role.

Basic Configuration¶

LOG_LEVEL

LOG_LEVEL = "DEBUG"

LOG_FILE

LOG_FILE = "/logs/lemur/lemur-test.log"

debug

Sets the flask debug flag to true (if supported by the webserver)

debug = False

Warning

This should never be used in a production environment as it exposes Lemur to remote code execution through the debug console.

CORS

Allows for cross domain requests, this is most commonly used for development but could be use in production if you decided to host the webUI on a different domain than the server.

Use this cautiously, if you’re not sure. Set it to False

CORS = False

SQLALCHEMY_DATABASE_URI

If you have ever used sqlalchemy before this is the standard connection string used. Lemur uses a postgres database and the connection string would look something like:

SQLALCHEMY_DATABASE_URI = 'postgresql://<user>:<password>@<hostname>:5432/lemur'

LEMUR_ALLOW_WEEKEND_EXPIRATION

Specifies whether to allow certificates created by Lemur to expire on weekends. Default is True.

LEMUR_RESTRICTED_DOMAINS

This allows the administrator to mark a subset of domains or domains matching a particular regex as restricted. This means that only an administrator is allows to issue the domains in question.

LEMUR_TOKEN_SECRET

The TOKEN_SECRET is the secret used to create JWT tokens that are given out to users. This should be securely generated and kept private.

LEMUR_TOKEN_SECRET = 'supersecret'

An example of how you might generate a random string:

>>> import random
>>> secret_key = ''.join(random.choice(string.ascii_uppercase) for x in range(6))
>>> secret_key = secret_key + ''.join(random.choice("~!@#$%^&*()_+") for x in range(6))
>>> secret_key = secret_key + ''.join(random.choice(string.ascii_lowercase) for x in range(6))
>>> secret_key = secret_key + ''.join(random.choice(string.digits) for x in range(6))

LEMUR_ENCRYPTION_KEYS

The LEMUR_ENCRYPTION_KEYS is used to encrypt data at rest within Lemur’s database. Without a key Lemur will refuse to start. Multiple keys can be provided to facilitate key rotation. The first key in the list is used for encryption and all keys are tried for decryption until one works. Each key must be 32 URL safe base-64 encoded bytes.

Running lemur create_config will securely generate a key for your configuration file. If you would like to generate your own, we recommend the following method:

>>> import os
>>> import base64
>>> base64.urlsafe_b64encode(os.urandom(32))

LEMUR_ENCRYPTION_KEYS = ['1YeftooSbxCiX2zo8m1lXtpvQjy27smZcUUaGmffhMY=', 'LAfQt6yrkLqOK5lwpvQcT4jf2zdeTQJV1uYeh9coT5s=']

Certificate Default Options¶

Lemur allows you to fine tune your certificates to your organization. The following defaults are presented in the UI and are used when Lemur creates the CSR for your certificates.

LEMUR_DEFAULT_COUNTRY

LEMUR_DEFAULT_COUNTRY = "US"

LEMUR_DEFAULT_STATE

LEMUR_DEFAULT_STATE = "California"

LEMUR_DEFAULT_LOCATION

LEMUR_DEFAULT_LOCATION = "Los Gatos"

LEMUR_DEFAULT_ORGANIZATION

LEMUR_DEFAULT_ORGANIZATION = "Netflix"

LEMUR_DEFAULT_ORGANIZATIONAL_UNIT

LEMUR_DEFAULT_ORGANIZATIONAL_UNIT = "Operations"

LEMUR_DEFAULT_ISSUER_PLUGIN

LEMUR_DEFAULT_ISSUER_PLUGIN = "verisign-issuer"

LEMUR_DEFAULT_AUTHORITY

LEMUR_DEFAULT_AUTHORITY = "verisign"

Notification Options¶

Lemur currently has very basic support for notifications. Currently only expiration notifications are supported. Actual notification is handled by the notification plugins that you have configured. Lemur ships with the ‘Email’ notification that allows expiration emails to be sent to subscribers.

Templates for expiration emails are located under lemur/plugins/lemur_email/templates and can be modified for your needs. Notifications are sent to the certificate creator, owner and security team as specified by the LEMUR_SECURITY_TEAM_EMAIL configuration parameter.

Certificates marked as inactive will not be notified of upcoming expiration. This enables a user to essentially silence the expiration. If a certificate is active and is expiring the above will be notified according to the LEMUR_DEFAULT_EXPIRATION_NOTIFICATION_INTERVALS or 30, 15, 2 days before expiration if no intervals are set.

Lemur supports sending certification expiration notifications through SES and SMTP.

LEMUR_EMAIL_SENDER

Specifies which service will be delivering notification emails. Valid values are SMTP or SES

Note

If using SMTP as your provider you will need to define additional configuration options as specified by Flask-Mail. See: Flask-Mail

If you are using SES the email specified by the LEMUR_MAIL configuration will need to be verified by AWS before you can send any mail. See: Verifying Email Address in Amazon SES

LEMUR_MAIL

Lemur sender’s email

LEMUR_MAIL = 'lemur.example.com'

LEMUR_SECURITY_TEAM_EMAIL

This is an email or list of emails that should be notified when a certificate is expiring. It is also the contact email address for any discovered certificate.

LEMUR_SECURITY_TEAM_EMAIL = ['security@example.com']

LEMUR_DEFAULT_EXPIRATION_NOTIFICATION_INTERVALS

Lemur notification intervals

LEMUR_DEFAULT_EXPIRATION_NOTIFICATION_INTERVALS = [30, 15, 2]

Authentication Options¶

Lemur currently supports Basic Authentication, Ping OAuth2, and Google out of the box. Additional flows can be added relatively easily. If you are not using an authentication provider you do not need to configure any of these options.

For more information about how to use social logins, see: Satellizer

ACTIVE_PROVIDERS

ACTIVE_PROVIDERS = ["ping", "google", "oauth2"]

PING_SECRET

PING_SECRET = 'somethingsecret'

PING_ACCESS_TOKEN_URL

PING_ACCESS_TOKEN_URL = "https://<yourpingserver>/as/token.oauth2"

PING_USER_API_URL

PING_USER_API_URL = "https://<yourpingserver>/idp/userinfo.openid"

PING_JWKS_URL

PING_JWKS_URL = "https://<yourpingserver>/pf/JWKS"

PING_NAME

PING_NAME = "Example Oauth2 Provider"

PING_CLIENT_ID

PING_CLIENT_ID = "client-id"

PING_REDIRECT_URI

PING_REDIRECT_URI = "https://<yourlemurserver>/api/1/auth/ping"

PING_AUTH_ENDPOINT

PING_AUTH_ENDPOINT = "https://<yourpingserver>/oauth2/authorize"

OAUTH2_SECRET

OAUTH2_SECRET = 'somethingsecret'

OAUTH2_ACCESS_TOKEN_URL

OAUTH2_ACCESS_TOKEN_URL = "https://<youroauthserver> /oauth2/v1/authorize"

OAUTH2_USER_API_URL

OAUTH2_USER_API_URL = "https://<youroauthserver>/oauth2/v1/userinfo"

OAUTH2_JWKS_URL

OAUTH2_JWKS_URL = "https://<youroauthserver>/oauth2/v1/keys"

OAUTH2_NAME

OAUTH2_NAME = "Example Oauth2 Provider"

OAUTH2_CLIENT_ID

OAUTH2_CLIENT_ID = "client-id"

OAUTH2_REDIRECT_URI

OAUTH2_REDIRECT_URI = "https://<yourlemurserver>/api/1/auth/oauth2"

OAUTH2_AUTH_ENDPOINT

OAUTH2_AUTH_ENDPOINT = "https://<youroauthserver>/oauth2/v1/authorize"

GOOGLE_CLIENT_ID

GOOGLE_CLIENT_ID = "client-id"

GOOGLE_SECRET

GOOGLE_SECRET = "somethingsecret"

Plugin Specific Options¶

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "ses:SendEmail"
      ],
      "Resource": "*"
    }
  ]
}

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action":
        "sts:AssumeRole",
      "Resource": "*"
    }
  ]
}

{
    "Statement": [
                {
                     "Action": [
                          "iam:ListServerCertificates",
                          "iam:UpdateServerCertificate",
                          "iam:GetServerCertificate",
                          "iam:UploadServerCertificate"
                     ],
                     "Resource": [
                          "*"
                     ],
                     "Effect": "Allow",
                     "Sid": "Stmt1404836868000"
                }
           ]
}

{
    "Statement": [
                {
                     "Action": [
                          "elasticloadbalancing:DescribeInstanceHealth",
                          "elasticloadbalancing:DescribeLoadBalancerAttributes",
                          "elasticloadbalancing:DescribeLoadBalancerPolicyTypes",
                          "elasticloadbalancing:DescribeLoadBalancerPolicies",
                          "elasticloadbalancing:DescribeLoadBalancers",
                          "elasticloadbalancing:DeleteLoadBalancerListeners",
                          "elasticloadbalancing:CreateLoadBalancerListeners"
                     ],
                     "Resource": [
                          "*"
                     ],
                     "Effect": "Allow",
                     "Sid": "Stmt1404841912000"
                }
           ]
}

{
  "Version": "2008-10-17",
  "Statement": [
    {
      "Sid": "",
      "Effect": "Allow",
      "Principal": {
        "AWS": [
          "arn:aws:iam::<awsaccountnumber>:role/LemurInstanceProfile",
        ]
      },
      "Action": "sts:AssumeRole"
    }
  ]
}

{
  "Version": "2008-10-17",
  "Statement": [
    {
      "Sid": "",
      "Effect": "Allow",
      "Principal": {
        "AWS": [
          "arn:aws:iam::<awsaccountnumber>:role/LemurInstanceProfile",
          "arn:aws:iam::<awsaccountnumber1>:role/LemurInstanceProfile",
        ]
      },
      "Action": "sts:AssumeRole"
    }
  ]
}

LEMUR_MAIL = 'lemur.example.com'

Builtin Commands¶

All commands default to ~/.lemur/lemur.conf.py if a configuration is not specified.

create_config¶

Creates a default configuration file for Lemur.

Path defaults to ~/.lemur/lemur.config.py

lemur create_config .

Note

This command is a special case and does not depend on the configuration file being set.

init¶

Initializes the configuration file for Lemur.

lemur -c /etc/lemur.conf.py init

start¶

Starts a Lemur service. You can also pass any flag that Gunicorn uses to specify the webserver configuration.

lemur start -w 6 -b 127.0.0.1:8080

db upgrade

Performs any needed database migrations.

lemur db upgrade

check_revoked¶

Traverses every certificate that Lemur is aware of and attempts to understand its validity. It utilizes both OCSP and CRL. If Lemur is unable to come to a conclusion about a certificates validity its status is marked ‘unknown’.

sync¶

Sync attempts to discover certificates in the environment that were not created by Lemur. If you wish to only sync a few sources you can pass a comma delimited list of sources to sync.

lemur sync -s source1,source2

Additionally you can also list the available sources that Lemur can sync.

lemur sync

notify¶

Will traverse all current notifications and see if any of them need to be triggered.

lemur notify

Sub-commands¶

Lemur includes several sub-commands for interacting with Lemur such as creating new users, creating new roles and even issuing certificates.

The best way to discover these commands is by using the built in help pages

lemur --help

and to get help on sub-commands

lemur certificates --help

Verisign/Symantec¶

Cryptography¶

Acme¶

Atlas¶

Email¶

Slack¶

AWS¶

AWS¶

Kubernetes¶

Java¶

Openssl¶

CFSSL¶

Digicert¶

Have an extension that should be listed here? Submit a pull request and we’ll get it added.

Want to create your own extension? See Structure to get started.

Documentation¶

If you’re looking to help document Lemur, you can get set up with Sphinx, our documentation tool, but first you will want to make sure you have a few things on your local system:

• python-dev (if you’re on OS X, you already have this)
• pip
• virtualenvwrapper

Once you’ve got all that, the rest is simple:

# If you have a fork, you'll want to clone it instead
git clone git://github.com/netflix/lemur.git

# Create a python virtualenv
mkvirtualenv lemur

# Make the magic happen
make dev-docs

Running make dev-docs will install the basic requirements to get Sphinx running.

Developing Against HEAD¶

We try to make it easy to get up and running in a development environment using a git checkout of Lemur. You’ll want to make sure you have a few things on your local system first:

• python-dev (if you’re on OS X, you already have this)
• pip
• virtualenv (ideally virtualenvwrapper)
• node.js (for npm and building css/javascript)
• (Optional) PostgreSQL

Once you’ve got all that, the rest is simple:

# If you have a fork, you'll want to clone it instead
git clone git://github.com/lemur/lemur.git

# Create a python virtualenv
mkvirtualenv lemur

# Make the magic happen
make

Running make will do several things, including:

• Setting up any submodules (including Bootstrap)
• Installing Python requirements
• Installing NPM requirements

Create a default Lemur configuration just as if this were a production instance:

lemur init

You’ll likely want to make some changes to the default configuration (we recommend developing against Postgres, for example). Once done, migrate your database using the following command:

lemur upgrade

Coding Standards¶

Lemur follows the guidelines laid out in pep8 with a little bit of flexibility on things like line length. We always give way for the Zen of Python. We also use strict mode for JavaScript, enforced by jshint.

You can run all linters with make lint, or respectively lint-python or lint-js.

Running the Test Suite¶

The test suite consists of multiple parts, testing both the Python and JavaScript components in Lemur. If you’ve setup your environment correctly, you can run the entire suite with the following command:

make test

If you only need to run the Python tests, you can do so with make test-python, as well as test-js for the JavaScript tests.

You’ll notice that the test suite is structured based on where the code lives, and strongly encourages using the mock library to drive more accurate individual tests.

Static Media¶

Lemur uses a library that compiles it’s static media assets (LESS and JS files) automatically. If you’re developing using runserver you’ll see changes happen not only in the original files, but also the minified or processed versions of the file.

If you’ve made changes and need to compile them by hand for any reason, you can do so by running:

lemur compilestatic

The minified and processed files should be committed alongside the unprocessed changes.

It’s also important to note that Lemur’s frontend and API are not tied together. The API does not serve any of the static assets, we rely on nginx or some other file server to server all of the static assets. During development that means we need an additional server to serve those static files for the GUI.

This is accomplished with a Gulp task:

./node_modules/.bin/gulp serve

The gulp task compiles all the JS/CSS/HTML files and opens the Lemur welcome page in your default browsers. Additionally any changes to made to the JS/CSS/HTML with be reloaded in your browsers.

Developing with Flask¶

Because Lemur is just Flask, you can use all of the standard Flask functionality. The only difference is you’ll be accessing commands that would normally go through manage.py using the lemur CLI helper instead.

For example, you probably don’t want to use lemur start for development, as it doesn’t support anything like automatic reloading on code changes. For that you’d want to use the standard builtin runserver command:

lemur runserver

DDL (Schema Changes)¶

Schema changes should always introduce the new schema in a commit, and then introduce code relying on that schema in a followup commit. This also means that new columns must be NULLable.

Removing columns and tables requires a slightly more painful flow, and should resemble the follow multi-commit flow:

• Remove all references to the column or table (but don’t remove the Model itself)
• Remove the model code
• Remove the table or column

Contributing Back Code¶

All patches should be sent as a pull request on GitHub, include tests, and documentation where needed. If you’re fixing a bug or making a large change the patch must include test coverage.

Uncertain about how to write tests? Take a look at some existing tests that are similar to the code you’re changing, and go from there.

You can see a list of open pull requests (pending changes) by visiting https://github.com/netflix/lemur/pulls

Pull requests should be against master and pass all TravisCI checks

Authentication¶

class lemur.auth.views.Google¶

Bases: flask_restful.Resource

endpoint = 'google'¶

mediatypes(resource_cls)¶

methods = ['POST']¶

post()¶

class lemur.auth.views.Login¶

Bases: flask_restful.Resource

Provides an endpoint for Lemur’s basic authentication. It takes a username and password combination and returns a JWT token.

This token token is required for each API request and must be provided in the Authorization Header for the request.

Authorization:Bearer <token>

Tokens have a set expiration date. You can inspect the token expiration by base64 decoding the token and inspecting it’s contents.

Note

It is recommended that the token expiration is fairly short lived (hours not days). This will largely depend on your uses cases but. It is important to not that there is currently no build in method to revoke a users token and force re-authentication.

endpoint = 'login'¶

mediatypes(resource_cls)¶

methods = ['POST']¶

post()¶

POST /auth/login¶

Login with username:password

Example request:

POST /auth/login HTTP/1.1
Host: example.com
Accept: application/json, text/javascript

{
  "username": "test",
  "password": "test"
}

Example response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: text/javascript

{
  "token": "12343243243"
}

Parameters:	username – username password – password
Status Codes:	401 Unauthorized – invalid credentials 200 OK – no error

class lemur.auth.views.OAuth2¶

Bases: flask_restful.Resource

endpoint = 'oauth2'¶

mediatypes(resource_cls)¶

methods = ['POST']¶

post()¶

class lemur.auth.views.Ping¶

Bases: flask_restful.Resource

This class serves as an example of how one might implement an SSO provider for use with Lemur. In this example we use an OpenIDConnect authentication flow, that is essentially OAuth2 underneath. If you have an OAuth2 provider you want to use Lemur there would be two steps:

1. Define your own class that inherits from flask.ext.restful.Resource and create the HTTP methods the provider uses for it’s callbacks.
2. Add or change the Lemur AngularJS Configuration to point to your new provider

endpoint = 'ping'¶

mediatypes(resource_cls)¶

methods = ['POST']¶

post()¶

class lemur.auth.views.Providers¶

Bases: flask_restful.Resource

endpoint = 'providers'¶

get()¶

mediatypes(resource_cls)¶

methods = ['GET']¶

Destinations¶

class lemur.destinations.views.CertificateDestinations¶

Bases: lemur.auth.service.AuthenticatedResource

Defines the ‘certificate/<int:certificate_id/destinations’’ endpoint

endpoint = 'certificateDestinations'¶

get(certificate_id)¶

GET /certificates/1/destinations¶

The current account list for a given certificates

Example request:

GET /certificates/1/destinations HTTP/1.1
Host: example.com
Accept: application/json, text/javascript

Example response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: text/javascript

{
  "items": [{
      "description": "test",
      "options": [{
          "name": "accountNumber",
          "required": true,
          "value": "111111111111111",
          "helpMessage": "Must be a valid AWS account number!",
          "validation": "/^[0-9]{12,12}$/",
          "type": "str"
      }],
      "id": 4,
      "plugin": {
          "pluginOptions": [{
              "name": "accountNumber",
              "required": true,
              "value": "111111111111111",
              "helpMessage": "Must be a valid AWS account number!",
              "validation": "/^[0-9]{12,12}$/",
              "type": "str"
          }],
          "description": "Allow the uploading of certificates to AWS IAM",
          "slug": "aws-destination",
          "title": "AWS"
      },
      "label": "test546"
  }
  "total": 1
}

Query Parameters:
	sortBy – field to sort on sortDir – asc or desc page – int default is 1 filter – key value pair format is k;v count – count number default is 10
Request Headers:
	Authorization – OAuth token to authenticate
Status Codes:	200 OK – no error

mediatypes(resource_cls)¶

methods = ['GET']¶

class lemur.destinations.views.Destinations¶

Bases: lemur.auth.service.AuthenticatedResource

delete(destination_id)¶

endpoint = 'destination'¶

get(destination_id)¶

GET /destinations/1¶

Get a specific account

Example request:

GET /destinations/1 HTTP/1.1
Host: example.com
Accept: application/json, text/javascript

Example response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: text/javascript

{
  "description": "test",
  "options": [{
      "name": "accountNumber",
      "required": true,
      "value": "111111111111111",
      "helpMessage": "Must be a valid AWS account number!",
      "validation": "/^[0-9]{12,12}$/",
      "type": "str"
  }],
  "id": 4,
  "plugin": {
      "pluginOptions": [{
          "name": "accountNumber",
          "required": true,
          "value": "111111111111111",
          "helpMessage": "Must be a valid AWS account number!",
          "validation": "/^[0-9]{12,12}$/",
          "type": "str"
      }],
      "description": "Allow the uploading of certificates to AWS IAM",
      "slug": "aws-destination",
      "title": "AWS"
  },
  "label": "test546"
}

Request Headers:
	Authorization – OAuth token to authenticate
Status Codes:	200 OK – no error

mediatypes(resource_cls)¶

methods = ['DELETE', 'GET', 'PUT']¶

put(destination_id, data=None)¶

PUT /destinations/1¶

Updates an account

Example request:

POST /destinations/1 HTTP/1.1
Host: example.com
Accept: application/json, text/javascript


{
  "description": "test33",
  "options": [{
      "name": "accountNumber",
      "required": true,
      "value": "34324324",
      "helpMessage": "Must be a valid AWS account number!",
      "validation": "/^[0-9]{12,12}$/",
      "type": "str"
  }],
  "id": 4,
  "plugin": {
      "pluginOptions": [{
          "name": "accountNumber",
          "required": true,
          "value": "34324324",
          "helpMessage": "Must be a valid AWS account number!",
          "validation": "/^[0-9]{12,12}$/",
          "type": "str"
      }],
      "description": "Allow the uploading of certificates to AWS IAM",
      "slug": "aws-destination",
      "title": "AWS"
  },
  "label": "test546"
}

Example response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: text/javascript

{
  "description": "test",
  "options": [{
      "name": "accountNumber",
      "required": true,
      "value": "111111111111111",
      "helpMessage": "Must be a valid AWS account number!",
      "validation": "/^[0-9]{12,12}$/",
      "type": "str"
  }],
  "id": 4,
  "plugin": {
      "pluginOptions": [{
          "name": "accountNumber",
          "required": true,
          "value": "111111111111111",
          "helpMessage": "Must be a valid AWS account number!",
          "validation": "/^[0-9]{12,12}$/",
          "type": "str"
      }],
      "description": "Allow the uploading of certificates to AWS IAM",
      "slug": "aws-destination",
      "title": "AWS"
  },
  "label": "test546"
}

Parameters:	accountNumber – aws account number label – human readable account label description – some description about the account
Request Headers:
	Authorization – OAuth token to authenticate
Status Codes:	200 OK – no error

class lemur.destinations.views.DestinationsList¶

Bases: lemur.auth.service.AuthenticatedResource

Defines the ‘destinations’ endpoint

endpoint = 'destinations'¶

get()¶

GET /destinations¶

The current account list

Example request:

GET /destinations HTTP/1.1
Host: example.com
Accept: application/json, text/javascript

Example response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: text/javascript

{
  "items": [{
      "description": "test",
      "options": [{
          "name": "accountNumber",
          "required": true,
          "value": "111111111111111",
          "helpMessage": "Must be a valid AWS account number!",
          "validation": "/^[0-9]{12,12}$/",
          "type": "str"
      }],
      "id": 4,
      "plugin": {
          "pluginOptions": [{
              "name": "accountNumber",
              "required": true,
              "value": "111111111111111",
              "helpMessage": "Must be a valid AWS account number!",
              "validation": "/^[0-9]{12,12}$/",
              "type": "str"
          }],
          "description": "Allow the uploading of certificates to AWS IAM",
          "slug": "aws-destination",
          "title": "AWS"
      },
      "label": "test546"
  }
  "total": 1
}

Query Parameters:
	sortBy – field to sort on sortDir – asc or desc page – int. default is 1 filter – key value pair format is k;v count – count number default is 10
Request Headers:
	Authorization – OAuth token to authenticate
Status Codes:	200 OK – no error

mediatypes(resource_cls)¶

methods = ['GET', 'POST']¶

post(data=None)¶

POST /destinations¶

Creates a new account

Example request:

POST /destinations HTTP/1.1
Host: example.com
Accept: application/json, text/javascript

{
  "description": "test33",
  "options": [{
      "name": "accountNumber",
      "required": true,
      "value": "34324324",
      "helpMessage": "Must be a valid AWS account number!",
      "validation": "/^[0-9]{12,12}$/",
      "type": "str"
  }],
  "id": 4,
  "plugin": {
      "pluginOptions": [{
          "name": "accountNumber",
          "required": true,
          "value": "34324324",
          "helpMessage": "Must be a valid AWS account number!",
          "validation": "/^[0-9]{12,12}$/",
          "type": "str"
      }],
      "description": "Allow the uploading of certificates to AWS IAM",
      "slug": "aws-destination",
      "title": "AWS"
  },
  "label": "test546"
}

Example response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: text/javascript

{
  "description": "test33",
  "options": [{
      "name": "accountNumber",
      "required": true,
      "value": "34324324",
      "helpMessage": "Must be a valid AWS account number!",
      "validation": "/^[0-9]{12,12}$/",
      "type": "str"
  }],
  "id": 4,
  "plugin": {
      "pluginOptions": [{
          "name": "accountNumber",
          "required": true,
          "value": "111111111111111",
          "helpMessage": "Must be a valid AWS account number!",
          "validation": "/^[0-9]{12,12}$/",
          "type": "str"
      }],
      "description": "Allow the uploading of certificates to AWS IAM",
      "slug": "aws-destination",
      "title": "AWS"
  },
  "label": "test546"
}

Parameters:	label – human readable account label description – some description about the account
Request Headers:
	Authorization – OAuth token to authenticate
Status Codes:	200 OK – no error

class lemur.destinations.views.DestinationsStats¶

Bases: lemur.auth.service.AuthenticatedResource

Defines the ‘certificates’ stats endpoint

endpoint = 'destinationStats'¶

get()¶

mediatypes(resource_cls)¶

methods = ['GET']¶

Notifications¶

class lemur.notifications.views.CertificateNotifications¶

Bases: lemur.auth.service.AuthenticatedResource

Defines the ‘certificate/<int:certificate_id/notifications’’ endpoint

endpoint = 'certificateNotifications'¶

get(certificate_id)¶

GET /certificates/1/notifications¶

The current account list for a given certificates

Example request:

GET /certificates/1/notifications HTTP/1.1
Host: example.com
Accept: application/json, text/javascript

Example response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: text/javascript

{
  "items": [
      {
          "description": "An example",
          "options": [
              {
                  "name": "interval",
                  "required": true,
                  "value": 555,
                  "helpMessage": "Number of days to be alert before expiration.",
                  "validation": "^\d+$",
                  "type": "int"
              },
              {
                  "available": [
                      "days",
                      "weeks",
                      "months"
                  ],
                  "name": "unit",
                  "required": true,
                  "value": "weeks",
                  "helpMessage": "Interval unit",
                  "validation": "",
                  "type": "select"
              },
              {
                  "name": "recipients",
                  "required": true,
                  "value": "kglisson@netflix.com,example@netflix.com",
                  "helpMessage": "Comma delimited list of email addresses",
                  "validation": "^([\w+-.%]+@[\w-.]+\.[A-Za-z]{2,4},?)+$",
                  "type": "str"
              }
          ],
          "label": "example",
          "pluginName": "email-notification",
          "active": true,
          "id": 2
      }
  ],
  "total": 1
 }

Query Parameters:
	sortBy – field to sort on sortDir – asc or desc page – int default is 1 filter – key value pair format is k;v count – count number default is 10
Request Headers:
	Authorization – OAuth token to authenticate
Status Codes:	200 OK – no error

mediatypes(resource_cls)¶

methods = ['GET']¶

class lemur.notifications.views.Notifications¶

Bases: lemur.auth.service.AuthenticatedResource

delete(notification_id)¶

endpoint = 'notification'¶

get(notification_id)¶

GET /notifications/1¶

Get a specific account

Example request:

GET /notifications/1 HTTP/1.1
Host: example.com
Accept: application/json, text/javascript

Example response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: text/javascript

{
  "description": "a test",
  "options": [
      {
          "name": "interval",
          "required": true,
          "value": 5,
          "helpMessage": "Number of days to be alert before expiration.",
          "validation": "^\d+$",
          "type": "int"
      },
      {
          "available": [
              "days",
              "weeks",
              "months"
          ],
          "name": "unit",
          "required": true,
          "value": "weeks",
          "helpMessage": "Interval unit",
          "validation": "",
          "type": "select"
      },
      {
          "name": "recipients",
          "required": true,
          "value": "kglisson@netflix.com,example@netflix.com",
          "helpMessage": "Comma delimited list of email addresses",
          "validation": "^([\w+-.%]+@[\w-.]+\.[A-Za-z]{2,4},?)+$",
          "type": "str"
      }
  ],
  "label": "test",
  "pluginName": "email-notification",
  "active": true,
  "id": 2
}

Request Headers:
	Authorization – OAuth token to authenticate
Status Codes:	200 OK – no error

mediatypes(resource_cls)¶

methods = ['DELETE', 'GET', 'PUT']¶

put(notification_id, data=None)¶

PUT /notifications/1¶

Updates an account

Example request:

POST /notifications/1 HTTP/1.1
Host: example.com
Accept: application/json, text/javascript

Example response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: text/javascript

{
  "id": 1,
  "accountNumber": 11111111111,
  "label": "labelChanged",
  "comments": "this is a thing"
}

Parameters:	accountNumber – aws account number label – human readable account label comments – some description about the account
Request Headers:
	Authorization – OAuth token to authenticate
Status Codes:	200 OK – no error

class lemur.notifications.views.NotificationsList¶

Bases: lemur.auth.service.AuthenticatedResource

Defines the ‘notifications’ endpoint

endpoint = 'notifications'¶

get()¶

GET /notifications¶

The current account list

Example request:

GET /notifications HTTP/1.1
Host: example.com
Accept: application/json, text/javascript

Example response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: text/javascript

{
  "items": [
      {
          "description": "An example",
          "options": [
              {
                  "name": "interval",
                  "required": true,
                  "value": 5,
                  "helpMessage": "Number of days to be alert before expiration.",
                  "validation": "^\d+$",
                  "type": "int"
              },
              {
                  "available": [
                      "days",
                      "weeks",
                      "months"
                  ],
                  "name": "unit",
                  "required": true,
                  "value": "weeks",
                  "helpMessage": "Interval unit",
                  "validation": "",
                  "type": "select"
              },
              {
                  "name": "recipients",
                  "required": true,
                  "value": "kglisson@netflix.com,example@netflix.com",
                  "helpMessage": "Comma delimited list of email addresses",
                  "validation": "^([\w+-.%]+@[\w-.]+\.[A-Za-z]{2,4},?)+$",
                  "type": "str"
              }
          ],
          "label": "example",
          "pluginName": "email-notification",
          "active": true,
          "id": 2
      }
  ],
  "total": 1
 }

Query Parameters:
	sortBy – field to sort on sortDir – asc or desc page – int default is 1 filter – key value pair format is k;v count – count number default is 10
Request Headers:
	Authorization – OAuth token to authenticate
Status Codes:	200 OK – no error

mediatypes(resource_cls)¶

methods = ['GET', 'POST']¶

post(data=None)¶

POST /notifications¶

Creates a new account

Example request:

POST /notifications HTTP/1.1
Host: example.com
Accept: application/json, text/javascript

{
  "description": "a test",
  "options": [
      {
          "name": "interval",
          "required": true,
          "value": 5,
          "helpMessage": "Number of days to be alert before expiration.",
          "validation": "^\d+$",
          "type": "int"
      },
      {
          "available": [
              "days",
              "weeks",
              "months"
          ],
          "name": "unit",
          "required": true,
          "value": "weeks",
          "helpMessage": "Interval unit",
          "validation": "",
          "type": "select"
      },
      {
          "name": "recipients",
          "required": true,
          "value": "kglisson@netflix.com,example@netflix.com",
          "helpMessage": "Comma delimited list of email addresses",
          "validation": "^([\w+-.%]+@[\w-.]+\.[A-Za-z]{2,4},?)+$",
          "type": "str"
      }
  ],
  "label": "test",
  "pluginName": "email-notification",
  "active": true,
  "id": 2
}

Example response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: text/javascript

{
  "description": "a test",
  "options": [
      {
          "name": "interval",
          "required": true,
          "value": 5,
          "helpMessage": "Number of days to be alert before expiration.",
          "validation": "^\d+$",
          "type": "int"
      },
      {
          "available": [
              "days",
              "weeks",
              "months"
          ],
          "name": "unit",
          "required": true,
          "value": "weeks",
          "helpMessage": "Interval unit",
          "validation": "",
          "type": "select"
      },
      {
          "name": "recipients",
          "required": true,
          "value": "kglisson@netflix.com,example@netflix.com",
          "helpMessage": "Comma delimited list of email addresses",
          "validation": "^([\w+-.%]+@[\w-.]+\.[A-Za-z]{2,4},?)+$",
          "type": "str"
      }
  ],
  "label": "test",
  "pluginName": "email-notification",
  "active": true,
  "id": 2
}

Parameters:	accountNumber – aws account number label – human readable account label comments – some description about the account
Request Headers:
	Authorization – OAuth token to authenticate
Status Codes:	200 OK – no error

Users¶

class lemur.users.views.CertificateUsers¶

Bases: lemur.auth.service.AuthenticatedResource

endpoint = 'certificateCreator'¶

get(certificate_id)¶

GET /certificates/1/creator¶

Get a certificate’s creator

Example request:

GET /certificates/1/creator HTTP/1.1
Host: example.com
Accept: application/json, text/javascript

Example response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: text/javascript

{
    "id": 1,
    "active": false,
    "email": "user1@example.com",
    "username": "user1",
    "profileImage": null
}

Request Headers:
	Authorization – OAuth token to authenticate
Status Codes:	200 OK – no error

mediatypes(resource_cls)¶

methods = ['GET']¶

class lemur.users.views.Me¶

Bases: lemur.auth.service.AuthenticatedResource

endpoint = 'me'¶

get()¶

GET /auth/me¶

Get the currently authenticated user

Example request:

GET /auth/me HTTP/1.1
Host: example.com
Accept: application/json, text/javascript

Example response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: text/javascript

{
    "id": 1,
    "active": false,
    "email": "user1@example.com",
    "username": "user1",
    "profileImage": null
}

Request Headers:
	Authorization – OAuth token to authenticate
Status Codes:	200 OK – no error

mediatypes(resource_cls)¶

methods = ['GET']¶

class lemur.users.views.RoleUsers¶

Bases: lemur.auth.service.AuthenticatedResource

endpoint = 'roleUsers'¶

get(role_id)¶

GET /roles/1/users¶

Get all users associated with a role

Example request:

GET /roles/1/users HTTP/1.1
Host: example.com
Accept: application/json, text/javascript

Example response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: text/javascript

{
  "items": [
      {
        "id": 2,
        "active": True,
        "email": "user2@example.com",
        "username": "user2",
        "profileImage": null
      },
      {
        "id": 1,
        "active": False,
        "email": "user1@example.com",
        "username": "user1",
        "profileImage": null
      }
    ]
  "total": 2
}

Request Headers:
	Authorization – OAuth token to authenticate
Status Codes:	200 OK – no error

mediatypes(resource_cls)¶

methods = ['GET']¶

class lemur.users.views.Users¶

Bases: lemur.auth.service.AuthenticatedResource

endpoint = 'user'¶

get(user_id)¶

GET /users/1¶

Get a specific user

Example request:

GET /users/1 HTTP/1.1
Host: example.com
Accept: application/json, text/javascript

Example response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: text/javascript

{
    "id": 1,
    "active": false,
    "email": "user1@example.com",
    "username": "user1",
    "profileImage": null
}

Request Headers:
	Authorization – OAuth token to authenticate
Status Codes:	200 OK – no error

mediatypes(resource_cls)¶

methods = ['GET', 'PUT']¶

put(user_id, data=None)¶

PUT /users/1¶

Update a user

Example request:

PUT /users/1 HTTP/1.1
Host: example.com
Accept: application/json, text/javascript

{
   "username": "user1",
   "email": "user1@example.com",
   "active": false,
   "roles": [
       {'id': 1} - or - {'name': 'myRole'}
   ]
}

Example response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: text/javascript

{
   "id": 1,
   "username": "user1",
   "email": "user1@example.com",
   "active": false,
   "profileImage": null
}

Request Headers:
	Authorization – OAuth token to authenticate
Status Codes:	200 OK – no error

class lemur.users.views.UsersList¶

Bases: lemur.auth.service.AuthenticatedResource

Defines the ‘users’ endpoint

endpoint = 'users'¶

get()¶

GET /users¶

The current user list

Example request:

GET /users HTTP/1.1
Host: example.com
Accept: application/json, text/javascript

Example response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: text/javascript

{
   "items": [
      {
         "id": 2,
         "active": True,
         "email": "user2@example.com",
         "username": "user2",
         "profileImage": null
      },
      {
         "id": 1,
         "active": False,
         "email": "user1@example.com",
         "username": "user1",
         "profileImage": null
      }
   ]
   "total": 2
}

Query Parameters:
	sortBy – field to sort on sortDir – asc or desc page – int default is 1 filter – key value pair format is k;v count – count number default is 10
Request Headers:
	Authorization – OAuth token to authenticate
Status Codes:	200 OK – no error

mediatypes(resource_cls)¶

methods = ['GET', 'POST']¶

post(data=None)¶

POST /users¶

Creates a new user

Example request:

POST /users HTTP/1.1
Host: example.com
Accept: application/json, text/javascript

{
   "username": "user3",
   "email": "user3@example.com",
   "active": true,
   "roles": [
      {'id': 1} - or - {'name': 'myRole'}
   ]
}

Example response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: text/javascript

{
    "id": 3,
    "active": True,
    "email": "user3@example.com,
    "username": "user3",
    "profileImage": null
}

Parameters:	username – username for new user email – email address for new user password – password for new user active – boolean, if the user is currently active roles – list, roles that the user should be apart of
Request Headers:
	Authorization – OAuth token to authenticate
Status Codes:	200 OK – no error

Roles¶

class lemur.roles.views.AuthorityRolesList¶

Bases: lemur.auth.service.AuthenticatedResource

Defines the ‘roles’ endpoint

endpoint = 'authorityRoles'¶

get(authority_id)¶

GET /authorities/1/roles¶

List of roles for a given authority

Example request:

GET /authorities/1/roles HTTP/1.1
Host: example.com
Accept: application/json, text/javascript

Example response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: text/javascript

{
  "items": [
      {
        "id": 1,
        "name": "role1",
        "description": "this is role1"
      },
      {
        "id": 2,
        "name": "role2",
        "description": "this is role2"
      }
    ]
  "total": 2
}

Query Parameters:
	sortBy – field to sort on sortDir – asc or desc page – int default is 1 filter – key value pair format is k;v count – count number default is 10
Request Headers:
	Authorization – OAuth token to authenticate
Status Codes:	200 OK – no error

mediatypes(resource_cls)¶

methods = ['GET']¶

class lemur.roles.views.RoleViewCredentials¶

Bases: lemur.auth.service.AuthenticatedResource

endpoint = 'roleCredentials`'¶

get(role_id)¶

GET /roles/1/credentials¶

View a roles credentials

Example request:

GET /users/1 HTTP/1.1
Host: example.com
Accept: application/json, text/javascript

Example response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: text/javascript

{
    "username: "ausername",
    "password": "apassword"
}

Request Headers:
	Authorization – OAuth token to authenticate
Status Codes:	200 OK – no error 403 Forbidden – unauthenticated

mediatypes(resource_cls)¶

methods = ['GET']¶

class lemur.roles.views.Roles¶

Bases: lemur.auth.service.AuthenticatedResource

delete(role_id)¶

DELETE /roles/1¶

Delete a role

Example request:

DELETE /roles/1 HTTP/1.1
Host: example.com
Accept: application/json, text/javascript

Example response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: text/javascript

{
   "message": "ok"
}

Request Headers:
	Authorization – OAuth token to authenticate
Status Codes:	200 OK – no error 403 Forbidden – unauthenticated

endpoint = 'role'¶

get(role_id)¶

GET /roles/1¶

Get a particular role

Example request:

GET /roles/1 HTTP/1.1
Host: example.com
Accept: application/json, text/javascript

Example response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: text/javascript

{
    "id": 1,
    "name": "role1",
    "description": "this is role1"
}

Request Headers:
	Authorization – OAuth token to authenticate
Status Codes:	200 OK – no error 403 Forbidden – unauthenticated

mediatypes(resource_cls)¶

methods = ['DELETE', 'GET', 'PUT']¶

put(role_id, data=None)¶

PUT /roles/1¶

Update a role

Example request:

PUT /roles/1 HTTP/1.1
Host: example.com
Accept: application/json, text/javascript

{
   "name": "role1",
   "description": "This is a new description"
}

Example response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: text/javascript

{
   "id": 1,
   "name": "role1",
   "description": "this is a new description"
}

Request Headers:
	Authorization – OAuth token to authenticate
Status Codes:	200 OK – no error 403 Forbidden – unauthenticated

class lemur.roles.views.RolesList¶

Bases: lemur.auth.service.AuthenticatedResource

Defines the ‘roles’ endpoint

endpoint = 'roles'¶

get()¶

GET /roles¶

The current role list

Example request:

GET /roles HTTP/1.1
Host: example.com
Accept: application/json, text/javascript

Example response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: text/javascript

{
  "items": [
      {
        "id": 1,
        "name": "role1",
        "description": "this is role1"
      },
      {
        "id": 2,
        "name": "role2",
        "description": "this is role2"
      }
    ]
  "total": 2
}

Query Parameters:
	sortBy – field to sort on sortDir – asc or desc page – int default is 1 filter – key value pair format is k;v count – count number default is 10
Request Headers:
	Authorization – OAuth token to authenticate
Status Codes:	200 OK – no error 403 Forbidden – unauthenticated

mediatypes(resource_cls)¶

methods = ['GET', 'POST']¶

post(data=None)¶

POST /roles¶

Creates a new role

Example request:

POST /roles HTTP/1.1
Host: example.com
Accept: application/json, text/javascript

{
   "name": "role3",
   "description": "this is role3",
   "username": null,
   "password": null,
   "users": [
      {'id': 1}
   ]
}

Example response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: text/javascript

{
    "id": 3,
    "description": "this is role3",
    "name": "role3"
}

Parameters:	name – name for new role description – description for new role password – password for new role username – username for new role users – list, of users to associate with role
Request Headers:
	Authorization – OAuth token to authenticate
Status Codes:	200 OK – no error 403 Forbidden – unauthenticated

class lemur.roles.views.UserRolesList¶

Bases: lemur.auth.service.AuthenticatedResource

Defines the ‘roles’ endpoint

endpoint = 'userRoles'¶

get(user_id)¶

GET /users/1/roles¶

List of roles for a given user

Example request:

GET /users/1/roles HTTP/1.1
Host: example.com
Accept: application/json, text/javascript

Example response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: text/javascript

{
  "items": [
      {
        "id": 1,
        "name": "role1",
        "description": "this is role1"
      },
      {
        "id": 2,
        "name": "role2",
        "description": "this is role2"
      }
    ]
  "total": 2
}

Query Parameters:
	sortBy – field to sort on sortDir – asc or desc page – int default is 1 filter – key value pair format is k;v count – count number default is 10
Request Headers:
	Authorization – OAuth token to authenticate
Status Codes:	200 OK – no error

mediatypes(resource_cls)¶

methods = ['GET']¶

Certificates¶

class lemur.certificates.views.CertificateExport¶

Bases: lemur.auth.service.AuthenticatedResource

endpoint = 'exportCertificate'¶

mediatypes(resource_cls)¶

methods = ['POST']¶

post(certificate_id, data=None)¶

POST /certificates/1/export¶

Export a certificate

Example request:

PUT /certificates/1/export HTTP/1.1
Host: example.com
Accept: application/json, text/javascript

{
  "export": {
      "plugin": {
          "pluginOptions": [{
              "available": ["Java Key Store (JKS)"],
              "required": true,
              "type": "select",
              "name": "type",
              "helpMessage": "Choose the format you wish to export",
              "value": "Java Key Store (JKS)"
          }, {
              "required": false,
              "type": "str",
              "name": "passphrase",
              "validation": "^(?=.*[A-Za-z])(?=.*\d)(?=.*[$@$!%*#?&])[A-Za-z\d$@$!%*#?&]{8,}$",
              "helpMessage": "If no passphrase is given one will be generated for you, we highly recommend this. Minimum length is 8."
          }, {
              "required": false,
              "type": "str",
              "name": "alias",
              "helpMessage": "Enter the alias you wish to use for the keystore."
          }],
          "version": "unknown",
          "description": "Attempts to generate a JKS keystore or truststore",
          "title": "Java",
          "author": "Kevin Glisson",
          "type": "export",
          "slug": "java-export"
      }
  }
}

Example response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: text/javascript

{
  "data": "base64encodedstring",
  "passphrase": "UAWOHW#&@_%!tnwmxh832025",
  "extension": "jks"
}

Request Headers:
	Authorization – OAuth token to authenticate
Status Codes:	200 OK – no error 403 Forbidden – unauthenticated

class lemur.certificates.views.CertificatePrivateKey¶

Bases: lemur.auth.service.AuthenticatedResource

endpoint = 'privateKeyCertificates'¶

get(certificate_id)¶

GET /certificates/1/key¶

Retrieves the private key for a given certificate

Example request:

GET /certificates/1/key HTTP/1.1
Host: example.com
Accept: application/json, text/javascript

Example response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: text/javascript

{
   "key": "-----BEGIN ...",
}

Request Headers:
	Authorization – OAuth token to authenticate
Status Codes:	200 OK – no error 403 Forbidden – unauthenticated

mediatypes(resource_cls)¶

methods = ['GET']¶

class lemur.certificates.views.Certificates¶

Bases: lemur.auth.service.AuthenticatedResource

endpoint = 'certificate'¶

get(certificate_id)¶

GET /certificates/1¶

One certificate

Example request:

GET /certificates/1 HTTP/1.1
Host: example.com
Accept: application/json, text/javascript

Example response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: text/javascript

{
  "status": null,
  "cn": "*.test.example.net",
  "chain": "",
  "authority": {
      "active": true,
      "owner": "secure@example.com",
      "id": 1,
      "description": "verisign test authority",
      "name": "verisign"
  },
  "owner": "joe@example.com",
  "serial": "82311058732025924142789179368889309156",
  "id": 2288,
  "issuer": "SymantecCorporation",
  "notBefore": "2016-06-03T00:00:00+00:00",
  "notAfter": "2018-01-12T23:59:59+00:00",
  "destinations": [],
  "bits": 2048,
  "body": "-----BEGIN CERTIFICATE-----...",
  "description": null,
  "deleted": null,
  "notifications": [{
      "id": 1
  }]
  "signingAlgorithm": "sha256",
  "user": {
      "username": "jane",
      "active": true,
      "email": "jane@example.com",
      "id": 2
  },
  "active": true,
  "domains": [{
      "sensitive": false,
      "id": 1090,
      "name": "*.test.example.net"
  }],
  "replaces": [],
  "replaced": [],
  "name": "WILDCARD.test.example.net-SymantecCorporation-20160603-20180112",
  "roles": [{
      "id": 464,
      "description": "This is a google group based role created by Lemur",
      "name": "joe@example.com"
  }],
  "san": null
}

Request Headers:
	Authorization – OAuth token to authenticate
Status Codes:	200 OK – no error 403 Forbidden – unauthenticated

mediatypes(resource_cls)¶

methods = ['GET', 'PUT']¶

put(certificate_id, data=None)¶

PUT /certificates/1¶

Update a certificate

Example request:

PUT /certificates/1 HTTP/1.1
Host: example.com
Accept: application/json, text/javascript

{
   "owner": "jimbob@example.com",
   "active": false
   "notifications": [],
   "destinations": [],
   "replacements": []
}

Example response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: text/javascript

{
  "status": null,
  "cn": "*.test.example.net",
  "chain": "",
  "authority": {
      "active": true,
      "owner": "secure@example.com",
      "id": 1,
      "description": "verisign test authority",
      "name": "verisign"
  },
  "owner": "joe@example.com",
  "serial": "82311058732025924142789179368889309156",
  "id": 2288,
  "issuer": "SymantecCorporation",
  "notBefore": "2016-06-03T00:00:00+00:00",
  "notAfter": "2018-01-12T23:59:59+00:00",
  "destinations": [],
  "bits": 2048,
  "body": "-----BEGIN CERTIFICATE-----...",
  "description": null,
  "deleted": null,
  "notifications": [{
      "id": 1
  }]
  "signingAlgorithm": "sha256",
  "user": {
      "username": "jane",
      "active": true,
      "email": "jane@example.com",
      "id": 2
  },
  "active": true,
  "domains": [{
      "sensitive": false,
      "id": 1090,
      "name": "*.test.example.net"
  }],
  "replaces": [],
  "name": "WILDCARD.test.example.net-SymantecCorporation-20160603-20180112",
  "roles": [{
      "id": 464,
      "description": "This is a google group based role created by Lemur",
      "name": "joe@example.com"
  }],
  "san": null
}

Request Headers:
	Authorization – OAuth token to authenticate
Status Codes:	200 OK – no error 403 Forbidden – unauthenticated