diff --git a/docs/administration/index.rst b/docs/administration/index.rst index fb527856..52c793c0 100644 --- a/docs/administration/index.rst +++ b/docs/administration/index.rst @@ -74,8 +74,6 @@ Basic Configuration The TOKEN_SECRET is the secret used to create JWT tokens that are given out to users. This should be securely generated and be kept private. - See `SECRET_KEY` for methods on secure secret generation. - :: LEMUR_TOKEN_SECRET = 'supersecret' @@ -122,7 +120,7 @@ and are used when Lemur creates the CSR for your certificates. :: - LEMUR_DEFAULT_STATE = "CA" + LEMUR_DEFAULT_STATE = "California" .. data:: LEMUR_DEFAULT_LOCATION @@ -152,15 +150,16 @@ and are used when Lemur creates the CSR for your certificates. Notification Options -------------------- -Lemur currently has very basic support for notifications. Notifications are sent to the certificate creator, owner and -security team as specified by the `SECURITY_TEAM_EMAIL` configuration parameter. +Lemur currently has very basic support for notifications. Currently only expiration notifications are supported. Actual notification +is handling by the notification plugins that you have configured. Lemur ships with the 'Email' notification that allows expiration emails +to be sent to subscribers. -The template for all of these notifications lives under lemur/template/event.html and can be easily modified to fit your -needs. +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 in-active 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 at 30, 15, 5, 2 days -respectively. +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. @@ -197,6 +196,16 @@ Lemur supports sending certification expiration notifications through SES and SM LEMUR_SECURITY_TEAM_EMAIL = ['security@example.com'] +.. data:: LEMUR_DEFAULT_EXPIRATION_NOTIFICATION_INTERVALS + :noindex: + + Lemur notification intervals + + :: + + LEMUR_DEFAULT_EXPIRATION_NOTIFICATION_INTERVALS = [30, 15, 2] + + Authority Options ----------------- @@ -309,9 +318,9 @@ In order for Lemur to manage it's own account and other accounts we must ensure Setting up IAM roles -------------------- -Lemur's aws plugin uses boto heavily to talk to all the AWS resources it manages. By default it uses the on-instance credentials to make the necessary calls. +Lemur's AWS plugin uses boto heavily to talk to all the AWS resources it manages. By default it uses the on-instance credentials to make the necessary calls. -In order to limit the permissions we will create a new two IAM roles for Lemur. You can name them whatever you would like but for example sake we will be calling them LemurInstanceProfile and Lemur. +In order to limit the permissions, we will create two new IAM roles for Lemur. You can name them whatever you would like but for example sake we will be calling them LemurInstanceProfile and Lemur. Lemur uses to STS to talk to different accounts. For managing one account this isn't necessary but we will still use it so that we can easily add new accounts. @@ -357,6 +366,11 @@ STS-AssumeRole Next we will create the the Lemur IAM role. Lemur +..note:: + +The default IAM role that Lemur assumes into is called `Lemur`, if you need to change this ensure you set `LEMUR_INSTANCE_PROFILE` to your role name in the configuration. + + Here is an example policy for Lemur: IAM-ServerCertificate @@ -614,7 +628,8 @@ that the `Authority` is associated with it Lemur allows that user to user/view/u This RBAC is also used when determining which users can access which certificate private key. Lemur's current permission structure is setup such that if the user is a `Creator` or `Owner` of a given certificate they are allow to view that -private key. +private key. Owners can also be a role name, such that any user with the same role as owner will be allowed to view the +private key information. These permissions are applied to the user upon login and refreshed on every request. diff --git a/docs/developer/plugins/index.rst b/docs/developer/plugins/index.rst index c813b4f7..03074995 100644 --- a/docs/developer/plugins/index.rst +++ b/docs/developer/plugins/index.rst @@ -215,7 +215,7 @@ certificate Lemur does not know about and adding the certificate to it's invento The `SourcePlugin` object has one default option of `pollRate`. This controls the number of seconds which to get new certificates. .. warning:: - Lemur currently has a very basic polling system of running a cron job every 15min to see which source plugins need to be run. A lock file is generated to guarentee that ] + Lemur currently has a very basic polling system of running a cron job every 15min to see which source plugins need to be run. A lock file is generated to guarantee that only one sync is running at a time. It also means that the minimum resolution of a source plugin poll rate is effectively 15min. You can always specify a faster cron job if you need a higher resolution sync job. diff --git a/docs/guide/certificate_extensions.png b/docs/guide/certificate_extensions.png new file mode 100644 index 00000000..f0c3b38f Binary files /dev/null and b/docs/guide/certificate_extensions.png differ diff --git a/docs/guide/create.png b/docs/guide/create.png new file mode 100644 index 00000000..3e118ffa Binary files /dev/null and b/docs/guide/create.png differ diff --git a/docs/guide/create_authority.png b/docs/guide/create_authority.png new file mode 100644 index 00000000..46d28436 Binary files /dev/null and b/docs/guide/create_authority.png differ diff --git a/docs/guide/create_authority_options.png b/docs/guide/create_authority_options.png new file mode 100644 index 00000000..2f765a19 Binary files /dev/null and b/docs/guide/create_authority_options.png differ diff --git a/docs/guide/create_certificate.png b/docs/guide/create_certificate.png new file mode 100644 index 00000000..61c9afb7 Binary files /dev/null and b/docs/guide/create_certificate.png differ diff --git a/docs/guide/create_role.png b/docs/guide/create_role.png new file mode 100644 index 00000000..622a49a6 Binary files /dev/null and b/docs/guide/create_role.png differ diff --git a/docs/guide/create_user.png b/docs/guide/create_user.png new file mode 100644 index 00000000..7e17815e Binary files /dev/null and b/docs/guide/create_user.png differ diff --git a/docs/guide/index.rst b/docs/guide/index.rst index 542e1733..bb369402 100644 --- a/docs/guide/index.rst +++ b/docs/guide/index.rst @@ -1,14 +1,95 @@ -Creating Users -============== +User Guide +========== + +These guides are quick tutorials on how to perform basic tasks in Lemur. + +Create a New User +~~~~~~~~~~~~~~~~~ +.. figure:: settings.png + + From the settings dropdown select "Users" + +.. figure:: create.png + + In the user table select "Create" + +.. figure:: create_user.png + + 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. -Creating Roles -============== +Create a New Role +~~~~~~~~~~~~~~~~~ + +.. figure:: settings.png + + From the settings dropdown select "Roles" + +.. figure:: create.png + + In the role table select "Create" + +.. figure:: create_role.png + + 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. -Creating Authorities -==================== +Create a New Authority +~~~~~~~~~~~~~~~~~~~~~~ + +.. figure:: create.png + + In the authority table select "Create" + +.. figure:: create_authority.png + + Enter a 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. + +.. figure:: create_authority_options.png + + 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. -Creating Certificates -===================== +Create a New Certificate +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. figure:: create.png + + In the certificate table select "Create" + +.. figure:: create_certificate.png + + Enter a 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. + +.. figure:: certificate_extensions.png + + 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 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. figure:: upload_certificate.png + + Enter a 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. diff --git a/docs/guide/settings.png b/docs/guide/settings.png new file mode 100644 index 00000000..021ede2c Binary files /dev/null and b/docs/guide/settings.png differ diff --git a/docs/guide/upload_certificate.png b/docs/guide/upload_certificate.png new file mode 100644 index 00000000..f3848b08 Binary files /dev/null and b/docs/guide/upload_certificate.png differ diff --git a/docs/quickstart/index.rst b/docs/quickstart/index.rst index 52865648..35a0b2a8 100644 --- a/docs/quickstart/index.rst +++ b/docs/quickstart/index.rst @@ -4,6 +4,8 @@ Quickstart This guide will step you through setting up a Python-based virtualenv, installing the required packages, and configuring the basic web service. This guide assumes a clean Ubuntu 14.04 instance, commands may differ based on the OS and configuration being used. +Pressed for time? See the Lemur docker file on `Github `_. + Dependencies ------------ @@ -18,6 +20,7 @@ Some basic prerequisites which you'll need in order to run Lemur: are largely handled for us. Lemur does **not** require AWS to function. Our guides and documentation try to be be as generic as possible and are not intended to document every step of launching Lemur into a given environment. + Setting up an Environment -------------------------