From 967c7ded8d421c38667fa136eafac37bcb8010f9 Mon Sep 17 00:00:00 2001 From: kevgliss Date: Thu, 31 Dec 2015 11:12:56 -0800 Subject: [PATCH] Improving documentation layout --- LICENSE | 1 - .../index.rst => administration.rst} | 291 ++++++++++-------- docs/conf.py | 10 +- docs/developer/index.rst | 81 ++++- docs/developer/internals/lemur.plugins.rst | 1 - docs/developer/internals/lemur.rst | 1 - docs/developer/internals/lemur.status.rst | 11 - docs/developer/plugins/index.rst | 3 - docs/developer/rest.rst | 66 ---- docs/index.rst | 16 +- docs/plugins/index.rst | 20 -- lemur/authorities/service.py | 4 - 12 files changed, 250 insertions(+), 255 deletions(-) rename docs/{administration/index.rst => administration.rst} (85%) delete mode 100644 docs/developer/internals/lemur.status.rst delete mode 100644 docs/developer/rest.rst delete mode 100644 docs/plugins/index.rst diff --git a/LICENSE b/LICENSE index 85c20990..ce743570 100644 --- a/LICENSE +++ b/LICENSE @@ -1,4 +1,3 @@ - Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ diff --git a/docs/administration/index.rst b/docs/administration.rst similarity index 85% rename from docs/administration/index.rst rename to docs/administration.rst index 9dd94952..110c6837 100644 --- a/docs/administration/index.rst +++ b/docs/administration.rst @@ -24,7 +24,6 @@ Basic Configuration LOG_FILE = "/logs/lemur/lemur-test.log" - .. data:: debug :noindex: @@ -34,7 +33,6 @@ Basic Configuration debug = False - .. warning:: This should never be used in a production environment as it exposes Lemur to remote code execution through the debug console. @@ -173,47 +171,123 @@ Lemur supports sending certification expiration notifications through SES and SM .. data:: LEMUR_EMAIL_SENDER :noindex: - Specifies which service will be delivering notification emails. Valid values are `SMTP` or `SES` + Specifies which service will be delivering notification emails. Valid values are `SMTP` or `SES` -.. note:: - If using STMP as your provider you will need to define additional configuration options as specified by Flask-Mail. - See: `Flask-Mail `_ + .. note:: + If using SMP 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 `_ - 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 `_ .. data:: LEMUR_MAIL :noindex: - Lemur sender's email + Lemur sender's email :: - LEMUR_MAIL = 'lemur.example.com' + LEMUR_MAIL = 'lemur.example.com' .. data:: LEMUR_SECURITY_TEAM_EMAIL :noindex: - 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. + 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_SECURITY_TEAM_EMAIL = ['security@example.com'] .. data:: LEMUR_DEFAULT_EXPIRATION_NOTIFICATION_INTERVALS :noindex: - Lemur notification intervals + Lemur notification intervals :: - LEMUR_DEFAULT_EXPIRATION_NOTIFICATION_INTERVALS = [30, 15, 2] + LEMUR_DEFAULT_EXPIRATION_NOTIFICATION_INTERVALS = [30, 15, 2] -Authority Options ------------------ +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 `_ + +.. data:: ACTIVE_PROVIDERS + :noindex: + + :: + + ACTIVE_PROVIDERS = ["ping", "google"] + +.. data:: PING_SECRET + :noindex: + + :: + + PING_SECRET = 'somethingsecret' + +.. data:: PING_ACCESS_TOKEN_URL + :noindex: + + :: + + PING_ACCESS_TOKEN_URL = "https:///as/token.oauth2" + + +.. data:: PING_USER_API_URL + :noindex: + + :: + + PING_USER_API_URL = "https:///idp/userinfo.openid" + +.. data:: PING_JWKS_URL + :noindex: + + :: + + PING_JWKS_URL = "https:///pf/JWKS" + +.. data:: PING_NAME + :noindex: + + :: + + PING_NAME = "Example Oauth2 Provider" + +.. data:: PING_CLIENT_ID + :noindex: + + :: + + PING_CLIENT_ID = "client-id" + +.. data:: GOOGLE_CLIENT_ID + :noindex: + + :: + + GOOGLE_CLIENT_ID = "client-id" + +.. data:: GOOGLE_SECRET + :noindex: + + :: + + GOOGLE_SECRET = "somethingsecret" + + +Plugin Specific Options +----------------------- + +Verisign Issuer Plugin +^^^^^^^^^^^^^^^^^^^^^^ Authorities will each have their own configuration options. There is currently just one plugin bundled with Lemur, Verisign/Symantec. Additional plugins may define additional options. Refer to the plugin's own documentation @@ -260,87 +334,16 @@ for those plugins. This is the root to be used for your CA chain -Authentication --------------- -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 `_ - -.. data:: ACTIVE_PROVIDERS - :noindex: - - :: - - ACTIVE_PROVIDERS = ["ping", "google"] - -.. data:: PING_SECRET - :noindex: - - :: - - PING_SECRET = 'somethingsecret' - -.. data:: PING_ACCESS_TOKEN_URL - :noindex: - - :: - - PING_ACCESS_TOKEN_URL = "https:///as/token.oauth2" - - -.. data:: PING_USER_API_URL - :noindex: - - :: - - PING_USER_API_URL = "https:///idp/userinfo.openid" - -.. data:: PING_JWKS_URL - :noindex: - - :: - - PING_JWKS_URL = "https:///pf/JWKS" - -.. data:: PING_NAME - :noindex: - - :: - - PING_NAME = "Example Oauth2 Provider" - -.. data:: PING_CLIENT_ID - :noindex: - - :: - - PING_CLIENT_ID = "client-id" - -.. data:: GOOGLE_CLIENT_ID - :noindex: - - :: - - GOOGLE_CLIENT_ID = "client-id" - -.. data:: GOOGLE_SECRET - :noindex: - - :: - - GOOGLE_SECRET = "somethingsecret" - - -AWS Plugin Configuration -======================== +AWS Source/Destination Plugin +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ In order for Lemur to manage its own account and other accounts we must ensure it has the correct AWS permissions. .. note:: AWS usage is completely optional. Lemur can upload, find and manage TLS certificates in AWS. But is not required to do so. 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. @@ -445,7 +448,8 @@ IAM-ServerCertificate Setting up STS access ---------------------- +""""""""""""""""""""" + Once we have setup our accounts we need to ensure that we create a trust relationship so that LemurInstanceProfile can assume the Lemur role. In the AWS console select the Lemur IAM role and select the Trust Relationships tab and click Edit Trust Relationship @@ -472,7 +476,7 @@ Below is an example policy: Adding N+1 accounts -------------------- +""""""""""""""""""" To add another account we go to the new account and create a new Lemur IAM role with the same policy as above. @@ -500,7 +504,7 @@ An example policy: } Setting up SES --------------- +"""""""""""""" Lemur has built in support for sending it's certificate notifications via Amazon's simple email service (SES). To force Lemur to use SES ensure you are the running as the IAM role defined above and that you have followed the steps outlined @@ -515,23 +519,6 @@ Will be the sender of all notifications, so ensure that it is verified with AWS. SES if the default notification gateway and will be used unless SMTP settings are configured in the application configuration settings. -Upgrading Lemur -=============== - -Lemur provides an easy way to upgrade between versions. Simply download the newest -version of Lemur from pypi and then apply any schema changes with the following command. - -.. code-block:: bash - - $ lemur db upgrade - -.. note:: Internally, this uses `Alembic `_ to manage database migrations. - -.. note:: By default Alembic looks for the `migrations` folder in the current working directory. -The migrations folder is located under `/lemur/migrations` if you are running the lemur command from any -location besides `/lemur` you will need to pass the `-d` flag to specify the absolute file path to the -`migrations` folder. - .. _CommandLineInterface: Command Line Interface @@ -641,32 +628,6 @@ and to get help on sub-commands lemur certificates --help -Identity and Access Management -============================== - -Lemur uses a Role Based Access Control (RBAC) mechanism to control which users have access to which resources. When a -user is first created in Lemur they can be assigned one or more roles. These roles are typically dynamically created -depending on a external identity provider (Google, LDAP, etc.,) or are hardcoded within Lemur and associated with special -meaning. - -Within Lemur there are three main permissions: AdminPermission, CreatorPermission, OwnerPermission. Sub-permissions such -as ViewPrivateKeyPermission are compositions of these three main Permissions. - -Lets take a look at how these permissions are used: - -Each `Authority` has a set of roles associated with it. If a user is also associated with the same roles -that the `Authority` is associated with, Lemur allows that user to user/view/update that `Authority`. - -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. 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. - -.. seealso:: - `Flask-Principal `_ - Upgrading Lemur =============== @@ -697,3 +658,61 @@ After you have the latest version of the Lemur code base you must run any needed This will ensure that any needed tables or columns are created or destroyed. + +.. note:: + Internally, this uses `Alembic `_ to manage database migrations. + +.. note:: + By default Alembic looks for the `migrations` folder in the current working directory.The migrations folder is + located under `/lemur/migrations` if you are running the lemur command from any location besides + `/lemur` you will need to pass the `-d` flag to specify the absolute file path to the `migrations` folder. + +Plugins +======= + +There are several interfaces currently available to extend Lemur. These are a work in +progress and the API is not frozen. + +Bundled Plugins +--------------- + +Lemur includes several plugins by default. Including extensive support for AWS, VeriSign/Symantec and CloudCA services. + +3rd Party Extensions +-------------------- + +The following extensions are available and maintained by members of the Lemur community: + +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 :doc:`../developer/plugins/index` to get started. + + +Identity and Access Management +============================== + +Lemur uses a Role Based Access Control (RBAC) mechanism to control which users have access to which resources. When a +user is first created in Lemur they can be assigned one or more roles. These roles are typically dynamically created +depending on a external identity provider (Google, LDAP, etc.,) or are hardcoded within Lemur and associated with special +meaning. + +Within Lemur there are three main permissions: AdminPermission, CreatorPermission, OwnerPermission. Sub-permissions such +as ViewPrivateKeyPermission are compositions of these three main Permissions. + +Lets take a look at how these permissions are used: + +Each `Authority` has a set of roles associated with it. If a user is also associated with the same roles +that the `Authority` is associated with, Lemur allows that user to user/view/update that `Authority`. + +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. 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. + +.. seealso:: + + `Flask-Principal `_ + diff --git a/docs/conf.py b/docs/conf.py index d890c50a..4f189350 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -101,9 +101,13 @@ pygments_style = 'sphinx' # -- Options for HTML output ---------------------------------------------- -# The theme to use for HTML and HTML Help pages. See the documentation for -# a list of builtin themes. -html_theme = 'default' +# on_rtd is whether we are on readthedocs.org, this line of code grabbed from docs.readthedocs.org +on_rtd = os.environ.get('READTHEDOCS', None) == 'True' + +if not on_rtd: # only import and set the theme if we're building docs locally + import sphinx_rtd_theme + html_theme = 'sphinx_rtd_theme' + html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the diff --git a/docs/developer/index.rst b/docs/developer/index.rst index 12aee616..c99f5049 100644 --- a/docs/developer/index.rst +++ b/docs/developer/index.rst @@ -180,19 +180,92 @@ You can see a list of open pull requests (pending changes) by visiting https://g Pull requests should be against **master** and pass all TravisCI checks -Plugins -======= + +Writing a Plugin +================ .. toctree:: - :maxdepth: 1 + :maxdepth: 2 plugins/index + +REST API +======== + +Lemur's front end is entirely API driven. Any action that you can accomplish via the UI can also be accomplished by the +UI. The following is documents and provides examples on how to make requests to the Lemur API. + +Authentication +-------------- + +.. automodule:: lemur.auth.views + :members: + :undoc-members: + :show-inheritance: + +Destinations +------------ + +.. automodule:: lemur.destinations.views + :members: + :undoc-members: + :show-inheritance: + +Notifications +------------- + +.. automodule:: lemur.notifications.views + :members: + :undoc-members: + :show-inheritance: + +Users +----- + +.. automodule:: lemur.users.views + :members: + :undoc-members: + :show-inheritance: + +Roles +----- + +.. automodule:: lemur.roles.views + :members: + :undoc-members: + :show-inheritance: + +Certificates +------------ + +.. automodule:: lemur.certificates.views + :members: + :undoc-members: + :show-inheritance: + +Authorities +----------- + +.. automodule:: lemur.authorities.views + :members: + :undoc-members: + :show-inheritance: + +Domains +------- + +.. automodule:: lemur.domains.views + :members: + :undoc-members: + :show-inheritance: + + Internals ========= .. toctree:: - :maxdepth: 1 + :maxdepth: 2 internals/lemur diff --git a/docs/developer/internals/lemur.plugins.rst b/docs/developer/internals/lemur.plugins.rst index a6ca6739..4b021c5c 100644 --- a/docs/developer/internals/lemur.plugins.rst +++ b/docs/developer/internals/lemur.plugins.rst @@ -27,6 +27,5 @@ Subpackages lemur.plugins.base lemur.plugins.bases lemur.plugins.lemur_aws - lemur.plugins.lemur_cloudca lemur.plugins.lemur_email lemur.plugins.lemur_verisign diff --git a/docs/developer/internals/lemur.rst b/docs/developer/internals/lemur.rst index eb6f225e..c498a3d7 100644 --- a/docs/developer/internals/lemur.rst +++ b/docs/developer/internals/lemur.rst @@ -96,5 +96,4 @@ Subpackages lemur.notifications lemur.plugins lemur.roles - lemur.status lemur.users diff --git a/docs/developer/internals/lemur.status.rst b/docs/developer/internals/lemur.status.rst deleted file mode 100644 index f28297d8..00000000 --- a/docs/developer/internals/lemur.status.rst +++ /dev/null @@ -1,11 +0,0 @@ -status Package -============== - -:mod:`views` Module -------------------- - -.. automodule:: lemur.status.views - :noindex: - :members: - :undoc-members: - :show-inheritance: diff --git a/docs/developer/plugins/index.rst b/docs/developer/plugins/index.rst index 03874813..6113f4a8 100644 --- a/docs/developer/plugins/index.rst +++ b/docs/developer/plugins/index.rst @@ -1,6 +1,3 @@ -Writing a Plugin -================ - Several interfaces exist for extending Lemur: * Issuer (lemur.plugins.base.issuer) diff --git a/docs/developer/rest.rst b/docs/developer/rest.rst deleted file mode 100644 index e4619385..00000000 --- a/docs/developer/rest.rst +++ /dev/null @@ -1,66 +0,0 @@ -Lemur's front end is entirely API driven. Any action that you can accomplish via the UI can also be accomplished by the -UI. The following is documents and provides examples on how to make requests to the Lemur API. - -Authentication --------------- - -.. automodule:: lemur.auth.views - :members: - :undoc-members: - :show-inheritance: - -Destinations ------------- - -.. automodule:: lemur.destinations.views - :members: - :undoc-members: - :show-inheritance: - -Notifications -------------- - -.. automodule:: lemur.notifications.views - :members: - :undoc-members: - :show-inheritance: - -Users ------ - -.. automodule:: lemur.users.views - :members: - :undoc-members: - :show-inheritance: - -Roles ------ - -.. automodule:: lemur.roles.views - :members: - :undoc-members: - :show-inheritance: - -Certificates ------------- - -.. automodule:: lemur.certificates.views - :members: - :undoc-members: - :show-inheritance: - -Authorities ------------ - -.. automodule:: lemur.authorities.views - :members: - :undoc-members: - :show-inheritance: - -Domains -------- - -.. automodule:: lemur.domains.views - :members: - :undoc-members: - :show-inheritance: diff --git a/docs/index.rst b/docs/index.rst index 0b0bbb29..12f74103 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -27,8 +27,7 @@ Administration .. toctree:: :maxdepth: 2 - administration/index - plugins/index + administration Developers ---------- @@ -38,14 +37,21 @@ Developers developer/index - -REST API +Security -------- .. toctree:: :maxdepth: 2 - developer/rest + security + +Doing a Release +--------------- + +.. toctree:: + :maxdepth: 1 + + doing-a-release FAQ ---- diff --git a/docs/plugins/index.rst b/docs/plugins/index.rst deleted file mode 100644 index ee6959ac..00000000 --- a/docs/plugins/index.rst +++ /dev/null @@ -1,20 +0,0 @@ -Plugins -======= - -There are several interfaces currently available to extend Lemur. These are a work in -progress and the API is not frozen. - -Bundled Plugins ---------------- - -Lemur includes several plugins by default. Including extensive support for AWS, VeriSign/Symantec and CloudCA services. - -3rd Party Extensions --------------------- - -The following extensions are available and maintained by members of the Lemur community: - -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 :doc:`../developer/plugins/index` to get started. \ No newline at end of file diff --git a/lemur/authorities/service.py b/lemur/authorities/service.py index 7d825c78..50812b0b 100644 --- a/lemur/authorities/service.py +++ b/lemur/authorities/service.py @@ -28,7 +28,6 @@ def update(authority_id, description=None, owner=None, active=None, roles=None): :param authority_id: :param roles: roles that are allowed to use this authority - :rtype : Authority :return: """ authority = get(authority_id) @@ -47,7 +46,6 @@ def create(kwargs): """ Create a new authority. - :rtype : Authority :return: """ @@ -123,7 +121,6 @@ def get(authority_id): """ Retrieves an authority given it's ID - :rtype : Authority :param authority_id: :return: """ @@ -135,7 +132,6 @@ def get_by_name(authority_name): Retrieves an authority given it's name. :param authority_name: - :rtype : Authority :return: """ return database.get(Authority, authority_name, field='name')