From 45043ab429d9478cef32e7e3c5b6a377f98fcef7 Mon Sep 17 00:00:00 2001 From: Traci Morrison Date: Thu, 23 Jan 2020 12:19:53 -0500 Subject: [PATCH] Edit for content audit --- _data/toc.yaml | 2 +- ee/ucp/admin/configure/configure-rbac-kube.md | 39 ++++----- .../admin/configure/enable-audit-logging.md | 85 +++++++------------ .../run-only-the-images-you-trust.md | 56 +++++------- .../authorization/create-teams-with-ldap.md | 47 +++++----- 5 files changed, 93 insertions(+), 136 deletions(-) diff --git a/_data/toc.yaml b/_data/toc.yaml index de5285d952..f6e0137ca5 100644 --- a/_data/toc.yaml +++ b/_data/toc.yaml @@ -1667,7 +1667,7 @@ manuals: - path: /ee/ucp/admin/configure/configure-rbac-kube/ title: Configure native Kubernetes role-based access control - path: /ee/ucp/admin/configure/enable-audit-logging/ - title: Create UCP audit logs + title: Audit logging on UCP - path: /ee/ucp/admin/configure/enable-saml-authentication/ title: Enable SAML authentication - path: /ee/ucp/admin/configure/integrate-saml/ diff --git a/ee/ucp/admin/configure/configure-rbac-kube.md b/ee/ucp/admin/configure/configure-rbac-kube.md index c6c36a06db..1e8acbece6 100644 --- a/ee/ucp/admin/configure/configure-rbac-kube.md +++ b/ee/ucp/admin/configure/configure-rbac-kube.md @@ -15,13 +15,10 @@ UCP 3.0 used its own role-based access control (RBAC) for Kubernetes clusters. N Kubernetes RBAC is turned on by default for Kubernetes clusters when customers upgrade to UCP 3.1. See [Using RBAC Authorization](https://kubernetes.io/docs/reference/access-authn-authz/rbac/) in the v1.11 documentation for more information about Kubernetes role-based access control. -Starting with UCP 3.1, Kubernetes and Swarm roles have separate views. You can view all the roles for a particular cluster under **Access Control** then **Roles**. Select Kubernetes or Swarm to view the specific roles for each. +Starting with UCP 3.1, Kubernetes and Swarm roles have separate views. You can view all of the roles for a particular cluster under **Access Control** > **Roles**. Select **Kubernetes** or **Swarm** to view the specific roles for each. ## Creating roles - -You create Kubernetes roles either through the CLI using `kubectl` or through the UCP web interface. - -To create a Kubernetes role in the UCP web interface: +You can create Kubernetes roles through either the CLI using [kubectl](https://kubernetes.io/docs/reference/kubectl/overview/) or the UCP user interface (the procedure that follows). 1. From the UCP UI, select **Access Control**. 2. From the left navigation menu, select **Roles**. @@ -29,33 +26,31 @@ To create a Kubernetes role in the UCP web interface: 3. Select the **Kubernetes** tab at the top of the window. 4. Select **Create** to create a Kubernetes role object in the following dialog: ![Kubernetes Role Creation in UCP](/ee/ucp/images/kube-role-create.png) -5. Select a namespace from the **Namespace** drop-down list. Selecting a specific namespace creates a role for use in that namespace, but selecting all namespaces creates a `ClusterRole` where you can create rules for cluster-scoped Kubernetes resources as well as namespaced resources. +5. Select a namespace from the **Namespace** drop-down list. Selecting a specific namespace creates a role for use in that namespace, however selecting all namespaces creates a ClusterRole where you can create rules for cluster-scoped Kubernetes resources as well as namespaced resources. 6. Provide the YAML for the role, either by entering it in the **Object YAML** editor or select **Click to upload a .yml file** to choose and upload a .yml file instead. -7. When you have finished specifying the YAML, Select **Create** to complete role creation. +7. Select **Create**. ## Creating role grants -Kubernetes provides 2 types of role grants: +Kubernetes provides two types of role grants, **ClusterRoleBinding** (which applies to all namespaces) and **RoleBinding** (which applies to a specific namespace). -- `ClusterRoleBinding` which applies to all namespaces -- `RoleBinding` which applies to a specific namespace +To create a grant for a Kubernetes role in the UCP UI: -To create a grant for a Kubernetes role in the UCP web interface: - -1. From the UCP UI, select **Access Control**. +1. Select **Access Control**. 2. From the left navigation menu, select **Grants**. ![Kubernetes Grants in UCP](/ee/ucp/images/v32grants.png) -3. Select the **Kubernetes** tab at the top of the window. All grants to Kubernetes roles can be viewed in the Kubernetes tab. -4. Select **Create New Grant** to start the Create Role Binding wizard and create a new grant for a given user, team or service. +3. Select the **Kubernetes** tab at the top of the window to view all of the grants available to Kubernetes roles. +4. Select **Create New Grant** to start the Create Role Binding wizard and create a new grant for a given user, team, or service. ![Kubernetes Create Role Binding in UCP](../../images/kube-grant-wizard.png) -5. Select the subject type. Your choices are: -- **All Users** -- **Organizations** -- **Service account** +5. Select the subject type, **All Users**, **Organizations**, or **Service Account**. 6. To create a user role binding, select a username from the **Users** drop-down list then select **Next**. 7. Select a resource set for the subject. The **default** namespace is automatically selected. To use a different namespace, select the **Select Namespace** button next to the desired namespace. For `Cluster Role Binding`, slide the **Apply Role Binding to all namespaces** selector to the right. ![Kubernetes Create User Role Binding in UCP](/ee/ucp/images/kube-grant-rolebinding.png) -8. Select **Next** to continue. -9. Select the **Cluster Role** from the drop-down list. If you create a `ClusterRoleBinding` (by selecting **Apply Role Binding to all namespaces**) then you may only select ClusterRoles. If you select a specific namespace, you can choose any role from that namespace or any ClusterRole. +8. Select **Next**. +9. Select the **Cluster Role** from the drop-down list. If you select **Apply Roles Binding to all namespaces** to create a ClusterRolebinding, only **ClusterRoles** can be selected. If, though, you select a specific namespace you can choose any role from that namespace or any ClusterRole. ![Kubernetes Select Cluster Role in UCP](/ee/ucp/images/kube-grant-roleselect.png) -10. Select **Create** to complete creating the grant. +10. Select **Create**. + +## Where to go next +* [Using RBAC Authorization](https://kubernetes.io/docs/reference/access-authn-authz/rbac/) +* [Find Kubernetes Resources](https://docs.docker.com/ee/ucp/kubernetes/kube-resources/) diff --git a/ee/ucp/admin/configure/enable-audit-logging.md b/ee/ucp/admin/configure/enable-audit-logging.md index 14cec2b507..abc52466f4 100644 --- a/ee/ucp/admin/configure/enable-audit-logging.md +++ b/ee/ucp/admin/configure/enable-audit-logging.md @@ -1,6 +1,6 @@ --- -title: Enable audit logging on UCP -description: Learn how to enable audit logging of all activity in UCP +title: Audit logging on UCP +description: Learn how to enable audit logging of all activity in UCP. keywords: logs, ucp, swarm, kubernetes, audits redirect_from: /ee/ucp/admin/configure/create-audit-logs/ --- @@ -8,92 +8,69 @@ redirect_from: /ee/ucp/admin/configure/create-audit-logs/ >{% include enterprise_label_shortform.md %} Audit logs are a chronological record of security-relevant activities by -individual users, administrators or software components that have affected the +individual users, administrators, or software components that have affected the system. They are focused on external user/agent actions and security rather than understanding state or events of the system itself. Audit logs capture all HTTP actions (GET, PUT, POST, PATCH, DELETE) to all UCP -API, Swarm API and Kubernetes API endpoints that are invoked (except for the -ignored list) and sent to Docker Engine via stdout. Creating audit logs is a UCP -component that integrates with Swarm, Kubernetes, and UCP APIs. +API, Swarm API, and Kubernetes API endpoints that are invoked (except for the +ignored list) and sent to Docker Engine through standard output (stdout). Creating audit logs is a UCP component that integrates with Swarm, Kubernetes, and UCP APIs. ## Logging levels -To allow more control to administrators over the audit logging, three audit -logging levels are provided: +Three audit logging levels are provided to give administrators more control: -- **None**: audit logging is disabled - -- **Metadata**: includes the following: +- **None:** Audit logging is disabled. +- **Metadata:** Includes the following: - Method and API endpoint for the request - UCP user who made the request - Response Status (success or failure) - Timestamp of the call - Object ID of any created or updated resource (for create or update API - calls). We do not include names of created or updated resources + calls). The names of created or updated resources are not included. - License Key - Remote Address - -- **Request**: includes all fields from the Metadata level as well as the +- **Request:** Includes all fields from the Metadata level as well as the request payload. > Note > > Once UCP audit logging has been enabled, audit logs can be found within the > container logs of the `ucp-controller` container on each UCP manager node. -> Please ensure you have a -> [logging driver](../../../../config/containers/logging/configure/) -> configured appropriately with log rotation set as audit logging can start to -> generate a lot of data. +> Ensure that you have a [logging driver](../../../../config/containers/logging/configure/) +> configured appropriately with log rotation set, as audit logging can generate a large amount of data. -## Benefits +## Benefits of audit logging -You can use audit logs to help with the following use cases: - -- **Historical troubleshooting** - Audit logs are helpful in determining a -sequence of past events that explain why an issue occurred. - -- **Security analysis and auditing** - Security is one of the primary uses for -audit logs. A full record of all user interactions with the container -infrastructure gives your security team full visibility to questionable or -attempted unauthorized accesses. - -- **Chargeback** - You can use audit logs and information about the resources to -generate chargeback information. - -- **Alerting** - If there is a watch on an event stream or a notification -created by the event, alerting features can be built on top of event tools that -generate alerts for ops teams (PagerDuty, OpsGenie, Slack, or custom solutions). +Audit logs can be of help with historical troubleshooting, security analysis and auditing, generating chargeback information, and creating useful alerts. ## Enabling UCP audit logging -UCP audit logging can be enabled via the UCP web user interface, the UCP API or -via the UCP configuration file. +Enable audit logging using either the UCP UI, the UCP API, or the UCP configuration file. -### Enabling UCP audit logging using the web UI +### Enabling UCP audit logging through the UI -1. Log in to the **UCP** Web User Interface -2. Navigate to **Admin Settings** -3. Select **Audit Logs** -4. In the **Configure Audit Log Level** section, select the relevant logging +1. Access the UCP UI and browse to the Admin Settings page. +2. Select **Audit Logs.** +3. In the **Configure Audit Log Level** section, select the relevant logging level. ![Enabling Audit Logging in UCP](../../images/auditlogging.png){: .with-border} -5. Click **Save** +4. Click **Save.** ### Enabling UCP audit logging using the API -1. Download the UCP Client bundle [Download client bundle from the command line](https://success.docker.com/article/download-client-bundle-from-the-cli). +1. Download the UCP Client bundle [from the command line](https://success.docker.com/article/download-client-bundle-from-the-cli). -2. Retrieve JSON for current audit log configuration. +2. Retrieve the JSON file for the current audit log configuration. ``` export DOCKER_CERT_PATH=~/ucp-bundle-dir/ curl --cert ${DOCKER_CERT_PATH}/cert.pem --key ${DOCKER_CERT_PATH}/key.pem --cacert ${DOCKER_CERT_PATH}/ca.pem -k -X GET https://ucp-domain/api/ucp/config/logging > auditlog.json ``` -3. Open auditlog.json to modify the 'auditlevel' field to `metadata` or `request`. +3. Open auditlog.json to modify the `auditlevel` field to `metadata` or `request`. ``` { @@ -111,7 +88,7 @@ level. ### Enabling UCP audit logging using the configuration file -Enabling UCP audit logging via the UCP configuration file can be done before +Enabling UCP audit logging through the UCP configuration file can be done before or after a UCP installation. Refer to the [UCP configuration file](./ucp-configuration-file/) topic for more information. The section of the UCP configuration file that controls UCP auditing logging is: @@ -124,22 +101,20 @@ The section of the UCP configuration file that controls UCP auditing logging is: The supported variables for `level` are `""`, `"metadata"` or `"request"`. -> Note +> Important > > The `support_dump_include_audit_logs` flag specifies whether user identification information from the ucp-controller container logs is included in the support dump. To prevent this information from being sent with the support dump, make sure that `support_dump_include_audit_logs` is set to `false`. When disabled, the support dump collection tool filters out any lines from the `ucp-controller` container logs that contain the substring `auditID`. {: .important} ## Accessing audit logs -The audit logs are exposed today through the `ucp-controller` logs. You can +The audit logs are exposed through the `ucp-controller` logs. You can access these logs locally through the Docker CLI or through an external -container logging solution, such as [ELK](https://success.docker.com/article/elasticsearch-logstash-kibana-logging) +container logging solution, such as [ELK](https://success.docker.com/article/elasticsearch-logstash-kibana-logging). ### Accessing audit logs using the Docker CLI -To access audit logs using the Docker CLI: - -1. Source a UCP Client Bundle +1. Source a UCP client bundle. 2. Run `docker logs` to obtain audit logs. In the following example, we are tailing the command to show the last log entry. @@ -204,7 +179,7 @@ events and may create a large amount of log entries. ## API endpoint information redacted -Information for the following API endpoints is redacted from the audit logs for security purposes: +Information for the following API endpoints is redacted from the audit logs for security purposes. - `/secrets/create` (POST) - `/secrets/{id}/update` (POST) @@ -215,5 +190,5 @@ Information for the following API endpoints is redacted from the audit logs for ## Where to go next -- [Collect UCP Cluster Metrics with Prometheus](collect-cluster-metrics.md) +- [Collect UCP cluster metrics with Prometheus](collect-cluster-metrics.md) - [Learn more about the UCP Configuration File](ucp-configuration-file.md) diff --git a/ee/ucp/admin/configure/run-only-the-images-you-trust.md b/ee/ucp/admin/configure/run-only-the-images-you-trust.md index 87222fbaa5..9130282e11 100644 --- a/ee/ucp/admin/configure/run-only-the-images-you-trust.md +++ b/ee/ucp/admin/configure/run-only-the-images-you-trust.md @@ -6,55 +6,45 @@ keywords: ucp, dtr, security, trust >{% include enterprise_label_shortform.md %} -With Docker Universal Control Plane you can enforce applications to only use -Docker images signed by UCP users you trust. When a user tries to deploy an -application to the cluster, UCP checks if the application uses a Docker image -that is not trusted, and won’t continue with the deployment if that’s the case. +With Docker Universal Control Plane (UCP), you can enforce applications to only use Docker images signed by UCP users you trust. Each time a user attempts to deploy an application to the cluster, UCP checks whether the application is using a trusted Docker image (and will halt the deployment if that is not the case). ![Enforce image signing](../../images/run-only-the-images-you-trust-1.svg) -By signing and verifying the Docker images, you ensure that the images being -used in your cluster are the ones you trust and haven’t been altered either in -the image registry or on their way from the image registry to your UCP cluster. +By signing and verifying Docker images, you ensure that: + +* The images used in your cluster are ones that you trust. +* The images have not been altered either in the image registry or on their way from the image registry to your UCP cluster. ## Example workflow -Here's an example of a typical workflow: - -1. A developer makes changes to a service and pushes their changes to a version - control system. -2. A CI system creates a build, runs tests, and pushes an image to DTR with the - new changes. -3. The quality engineering team pulls the image and runs more tests. If - everything looks good they sign and push the image. -4. The IT operations team deploys a service. If the image used for the service - was signed by the QA team, UCP deploys it. Otherwise UCP refuses to deploy. +1. A developer makes changes to a service and pushes the changes to a version control system. +2. A continuous integration (CI) system creates a build, runs tests, and pushes an image to Docker Trusted Registry (DTR) with the new changes. +3. The quality engineering team pulls the image and runs more tests. If the tests are successful, the team signs and then pushes the image. +4. The IT operations team deploys a service. If the image used for the service was signed by the QA team, UCP deploys it. Otherwise, UCP refuses to deploy the image. ## Configure UCP -To configure UCP to only allow running services that use Docker images you -trust, go to the UCP web UI, navigate to the **Admin Settings** page, and in -the left pane, click **Docker Content Trust**. +To configure UCP to only allow running services that use Docker trusted images: -Select the **Run Only Signed Images** option to only allow deploying -applications if they use images you trust. +1. Access the UCP UI and browse to the **Admin Settings** page. +2. In the left navigation pane, click **Docker Content Trust**. +3. Select the **Run only signed images** option. -![UCP settings](../../images/run-only-the-images-you-trust-2.png){: .with-border} + ![UCP settings](../../images/run-only-the-images-you-trust-2.png){: .with-border} -With this setting, UCP allows deploying any image as long as the image has -been signed. It doesn't matter who signed the image. + With this setting, UCP allows deploying any image as long as the image has + been signed. -To enforce that the image needs to be signed by specific teams, click **Add Team** -and select those teams from the list. + To enforce the requirement that the image be signed by specific teams, click **Add Team** and select the pertinent teams from the list. -![UCP settings](../../images/run-only-the-images-you-trust-3.png){: .with-border} + ![UCP settings](../../images/run-only-the-images-you-trust-3.png){: .with-border} -If you specify multiple teams, the image needs to be signed by a member of each -team, or someone that is a member of all those teams. + If you specify multiple teams, the image needs to be signed by a member of each + team, or by someone that is a member of all of those teams. -Click **Save** for UCP to start enforcing the policy. From now on, existing -services will continue running and can be restarted if needed, but UCP will only -allow deploying new services that use a trusted image. +4. Click **Save.** + + At this point, UCP starts enforcing the policy. Existing services will continue running and can be restarted if needed, however UCP only allows the deployment of new services that use a trusted image. ## Where to go next diff --git a/ee/ucp/authorization/create-teams-with-ldap.md b/ee/ucp/authorization/create-teams-with-ldap.md index 075d2babdc..f16a211e25 100644 --- a/ee/ucp/authorization/create-teams-with-ldap.md +++ b/ee/ucp/authorization/create-teams-with-ldap.md @@ -6,28 +6,25 @@ keywords: authorize, authentication, users, teams, UCP, LDAP >{% include enterprise_label_shortform.md %} -To enable LDAP in UCP and sync to your LDAP directory: +If Docker Enterprise is configured to sync users with a Lightweight Directory Access Protocol (LDAP) directory server, you can enable the syncing of new team members to occur either when creating a new team or when modifying settings of an existing team. -1. Click **Admin Settings** under your username drop down. +To enable LDAP in Docker Universal Control Place (UCP) and sync to your LDAP directory: + +1. Click **Admin Settings** under your username drop-down list. 2. Click **Authentication & Authorization**. -3. Scroll down and click `Yes` by **LDAP Enabled**. A list of LDAP settings displays. +3. Scroll down and click `Yes` next to **LDAP Enabled**. A list of LDAP settings displays. 4. Input values to match your LDAP server installation. 5. Test your configuration in UCP. 6. Manually create teams in UCP to mirror those in LDAP. 6. Click **Sync Now**. -If Docker Enterprise is configured to sync users with your organization's LDAP directory -server, you can enable syncing the new team's members when creating a new team -or when modifying settings of an existing team. - -For more, see: [Integrate with an LDAP Directory](../admin/configure/external-auth/index.md). +For more information, see [Integrate with an LDAP Directory](../admin/configure/external-auth/index.md). ![](../images/create-and-manage-teams-5.png){: .with-border} ## Binding to the LDAP server -There are two methods for matching group members from an LDAP directory, direct -bind and search bind. +There are two methods for matching group members from an LDAP directory, **direct bind** and **search bind**. Select **Immediately Sync Team Members** to run an LDAP sync operation immediately after saving the configuration for the team. It may take a moment @@ -35,24 +32,24 @@ before the members of the team are fully synced. ### Match Group Members (Direct Bind) -This option specifies that team members should be synced directly with members -of a group in your organization's LDAP directory. The team's membership will by -synced to match the membership of the group. - -- **Group DN**: The distinguished name of the group from which to select users. -- **Group Member Attribute**: The value of this group attribute corresponds to - the distinguished names of the members of the group. +The Direct Bind option specifies that team members be synced directly with member of a group in the organization's LDAP directory. The team's membership will be synced to match the membership of the group. +| Option | Description | +|------------------------|------------------------------------------| +| Group DN | The distinguished name (DN) of the group from which to select users. | +| Group Member Attribute | The value of this group attribute corresponds to the distinguished names of the members of the group. | ### Match Search Results (Search Bind) -This option specifies that team members should be synced using a search query -against your organization's LDAP directory. The team's membership will be +The Search Bind option specifies that team members be synced using a search query against the organization's LDAP directory. The team's membership will be synced to match the users in the search results. -- **Search Base DN**: Distinguished name of the node in the directory tree where - the search should start looking for users. -- **Search Filter**: Filter to find users. If null, existing users in the search - scope are added as members of the team. -- **Search subtree**: Defines search through the full LDAP tree, not just one - level, starting at the Base DN. +| Option | Description | +|----------------|------------------------------------------| +| Search Base DN | DN of the node in the directory tree where the search should start looking for users. | +| Search Filter | Filter to find users. If null, existing users in the search scope are added as members of the team. | +| Search subtree | Defines search through the full LDAP tree, not just one level, starting at the Base DN. | + +## Where to go next +* [Integrate with an LDAP directory](https://docs.docker.com/ee/ucp/admin/configure/external-auth/) +* [Create users and teams manually](https://docs.docker.com/ee/ucp/authorization/create-users-and-teams-manually/)