add integration guides

coder · matifali · May 22, 2024 · May 23, 2024 · May 23, 2024 · May 23, 2024
commit 4098a8c75d43eee5b51dd577ba0053d67511a77b
diff --git a/docs/README.md b/docs/README.md
@@ -40,7 +40,7 @@ and whatever else Terraform lets you dream up.
 
 ## IDE Support
 
-You can use any Web IDE ([code-server](https://github.com/coder/code-server), [projector](https://github.com/JetBrains/projector-server), [Jupyter](https://jupyter.org/), etc.), [JetBrains Gateway](https://www.jetbrains.com/remote-development/gateway/), [VS Code Remote](https://code.visualstudio.com/docs/remote/ssh-tutorial) or even a file sync such as [mutagen](https://mutagen.io/).
+You can use any Web IDE ([code-server](https://github.com/coder/code-server), [projector](https://github.com/JetBrains/projector-server), [Jupyter](https://jupyter.org/), etc.), [JetBrains Gateway](https://www.JetBrains.com/remote-development/gateway/), [VS Code Remote](https://code.visualstudio.com/docs/remote/ssh-tutorial) or even a file sync such as [mutagen](https://mutagen.io/).
 
 <p align="center">
   <img src="./images/ide-icons.svg" height=72>

diff --git a/docs/admin/integrations/artifactory-integration.md b/docs/admin/integrations/artifactory-integration.md
@@ -0,0 +1,176 @@
+# JFrog Artifactory Integration
+
+<div>
+  <a href="https://github.com/matifali" style="text-decoration: none; color: inherit;">
+    <span style="vertical-align:middle;">M Atif Ali</span>
+    <img src="https://github.com/matifali.png" width="24px" height="24px" style="vertical-align:middle; margin: 0px;"/>
+  </a>
+</div>
+January 24, 2024
+
+---
+
+Use Coder and JFrog Artifactory together to secure your development environments
+without disturbing your developers' existing workflows.
+
+This guide will demonstrate how to use JFrog Artifactory as a package registry
+within a workspace.
+
+## Requirements
+
+- A JFrog Artifactory instance
+- 1:1 mapping of users in Coder to users in Artifactory by email address or
+  username
+- Repositories configured in Artifactory for each package manager you want to
+  use
+
+## Provisioner Authentication
+
+The most straight-forward way to authenticate your template with Artifactory is
+by using our official Coder [modules](https://registry.coder.com). We publish
+two type of modules that automate the JFrog Artifactory and Coder integration.
+
+1. [JFrog-OAuth](https://registry.coder.com/modules/jfrog-oauth)
+2. [JFrog-Token](https://registry.coder.com/modules/jfrog-token)
+
+### JFrog-OAuth
+
+This module is usable by JFrog self-hosted (on-premises) Artifactory as it
+requires configuring a custom integration. This integration benefits from
+Coder's [external-auth](https://coder.com/docs/v2/latest/admin/external-auth)
+feature and allows each user to authenticate with Artifactory using an OAuth
+flow and issues user-scoped tokens to each user.
+
+To set this up, follow these steps:
+
+1. Modify your Helm chart `values.yaml` for JFrog Artifactory to add,
+
+```yaml
+artifactory:
+  enabled: true
+  frontend:
+  extraEnvironmentVariables:
+    - name: JF_FRONTEND_FEATURETOGGLER_ACCESSINTEGRATION
+      value: "true"
+  access:
+  accessConfig:
+    integrations-enabled: true
+    integration-templates:
+      - id: "1"
+        name: "CODER"
+        redirect-uri: "https://CODER_URL/external-auth/jfrog/callback"
+        scope: "applied-permissions/user"
+```
+
+> Note Replace `CODER_URL` with your Coder deployment URL, e.g.,
+> <coder.example.com>
+
+2. Create a new Application Integration by going to
+   <https://JFROG_URL/ui/admin/configuration/integrations/new> and select the
+   Application Type as the integration you created in step 1.
+
+![JFrog Platform new integration](../images/guides/artifactory-integration/jfrog-oauth-app.png)
+
+3. Add a new
+   [external authentication](https://coder.com/docs/v2/latest/admin/external-auth)
+   to Coder by setting these env variables,
+
+```env
+# JFrog Artifactory External Auth
+CODER_EXTERNAL_AUTH_1_ID="jfrog"
+CODER_EXTERNAL_AUTH_1_TYPE="jfrog"
+CODER_EXTERNAL_AUTH_1_CLIENT_ID="YYYYYYYYYYYYYYY"
+CODER_EXTERNAL_AUTH_1_CLIENT_SECRET="XXXXXXXXXXXXXXXXXXX"
+CODER_EXTERNAL_AUTH_1_DISPLAY_NAME="JFrog Artifactory"
+CODER_EXTERNAL_AUTH_1_DISPLAY_ICON="/icon/jfrog.svg"
+CODER_EXTERNAL_AUTH_1_AUTH_URL="https://JFROG_URL/ui/authorization"
+CODER_EXTERNAL_AUTH_1_SCOPES="applied-permissions/user"
+```
+
+> Note Replace `JFROG_URL` with your JFrog Artifactory base URL, e.g.,
+> <example.jfrog.io>
+
+4. Create or edit a Coder template and use the
+   [JFrog-OAuth](https://registry.coder.com/modules/jfrog-oauth) module to
+   configure the integration.
+
+```hcl
+module "jfrog" {
+  source = "registry.coder.com/modules/jfrog-oauth/coder"
+  version = "1.0.0"
+  agent_id = coder_agent.example.id
+  jfrog_url = "https://jfrog.example.com"
+  configure_code_server = true # this depends on the code-server
+  username_field = "username" # If you are using GitHub to login to both Coder and Artifactory, use username_field = "username"
+  package_managers = {
+    "npm": "npm",
+    "go": "go",
+    "pypi": "pypi"
+  }
+}
+```
+
+### JFrog-Token
+
+This module makes use of the
+[Artifactory terraform provider](https://registry.terraform.io/providers/jfrog/artifactory/latest/docs)
+and an admin-scoped token to create user-scoped tokens for each user by matching
+their Coder email or username with Artifactory. This can be used for both SaaS
+and self-hosted(on-premises) Artifactory instances.
+
+To set this up, follow these steps:
+
+1. Get a JFrog access token from your Artifactory instance. The token must be an
+   [admin token](https://registry.terraform.io/providers/jfrog/artifactory/latest/docs#access-token)
+   with scope `applied-permissions/admin`.
+2. Create or edit a Coder template and use the
+   [JFrog-Token](https://registry.coder.com/modules/jfrog-token) module to
+   configure the integration and pass the admin token. It is recommended to
+   store the token in a sensitive terraform variable to prevent it from being
+   displayed in plain text in the terraform state.
+
+```hcl
+variable "artifactory_access_token" {
+  type      = string
+  sensitive = true
+}
+
+module "jfrog" {
+  source = "registry.coder.com/modules/jfrog-token/coder"
+  version = "1.0.0"
+  agent_id = coder_agent.example.id
+  jfrog_url = "https://example.jfrog.io"
+  configure_code_server = true # this depends on the code-server
+  artifactory_access_token = var.artifactory_access_token
+  package_managers = {
+    "npm": "npm",
+    "go": "go",
+    "pypi": "pypi"
+  }
+}
+```
+
+<blockquote class="info">
+The admin-level access token is used to provision user tokens and is never exposed to
+developers or stored in workspaces.
+</blockquote>
+
+If you do not want to use the official modules, you can check example template
+that uses Docker as the underlying compute
+[here](https://github.com/coder/coder/tree/main/examples/jfrog/docker). The same
+concepts apply to all compute types.
+
+## Offline Deployments
+
+See the [offline deployments](../templates/modules.md#offline-installations)
+section for instructions on how to use coder-modules in an offline environment
+with Artifactory.
+
+## More reading
+
+- See the full example template
+  [here](https://github.com/coder/coder/tree/main/examples/jfrog/docker).
+- To serve extensions from your own VS Code Marketplace, check out
+  [code-marketplace](https://github.com/coder/code-marketplace#artifactory-storage).
+- To store templates in Artifactory, check out our
+  [Artifactory modules](../templates/modules.md#artifactory) docs.
diff --git a/docs/admin/integrations/island-integration.md b/docs/admin/integrations/island-integration.md
@@ -0,0 +1,163 @@
+# Island Browser Integration
+
+<div>
+  <a href="https://github.com/ericpaulsen" style="text-decoration: none; color: inherit;">
+    <span style="vertical-align:middle;">Eric Paulsen</span>
+    <img src="https://github.com/ericpaulsen.png" width="24px" height="24px" style="vertical-align:middle; margin: 0px;"/>
+  </a>
+</div>
+April 24, 2024
+
+---
+
+[Island](https://www.island.io/) is an enterprise-grade browser, offering a
+Chromium-based experience similar to popular web browsers like Chrome and Edge.
+It includes built-in security features for corporate applications and data,
+aiming to bridge the gap between consumer-focused browsers and the security
+needs of the enterprise.
+
+Coder natively integrates with Island's feature set, which include data loss
+protection (DLP), application awareness, browser session recording, and single
+sign-on (SSO). This guide intends to document these feature categories and how
+they apply to your Coder deployment.
+
+## General Configuration
+
+### Create an Application Group for Coder
+
+We recommend creating an Application Group specific to Coder in the Island
+Management console. This Application Group object will be referenced when
+creating browser policies.
+
+[See the Island documentation for creating an Application Group](https://documentation.island.io/docs/create-and-configure-an-application-group-object).
+
+## Advanced Data Loss Protection
+
+Integrate Island's advanced data loss prevention (DLP) capabilities with Coder's
+cloud development environment (CDE), enabling you to control the “last mile”
+between developers’ CDE and their local devices, ensuring that sensitive IP
+remains in your centralized environment.
+
+### Block cut, copy, paste, printing, screen share
+
+1. [Create a Data Sandbox Profile](https://documentation.island.io/docs/create-and-configure-a-data-sandbox-profile)
+
+1. Configure the following actions to allow/block (based on your security
+   requirements):
+
+- Screenshot and Screen Share
+- Printing
+- Save Page
+- Clipboard Limitations
+
+1. [Create a Policy Rule](https://documentation.island.io/docs/create-and-configure-a-policy-rule-general)
+   to apply the Data Sandbox Profile
+
+1. Define the Coder Application group as the Destination Object
+
+1. Define the Data Sandbox Profile as the Action in the Last Mile Protection
+   section
+
+### Conditionally allow copy on Coder's CLI authentication page
+
+1. [Create a URL Object](https://documentation.island.io/docs/create-and-configure-a-policy-rule-general)
+   with the following configuration:
+
+- **Include**
+- **URL type**: Wildcard
+- **URL address**: `coder.example.com/cli-auth`
+- **Casing**: Insensitive
+
+1. [Create a Data Sandbox Profile](https://documentation.island.io/docs/create-and-configure-a-data-sandbox-profile)
+
+1. Configure action to allow copy/paste
+
+1. [Create a Policy Rule](https://documentation.island.io/docs/create-and-configure-a-policy-rule-general)
+   to apply the Data Sandbox Profile
+
+1. Define the URL Object you created as the Destination Object
+
+1. Define the Data Sandbox Profile as the Action in the Last Mile Protection
+   section
+
+### Prevent file upload/download from the browser
+
+1. Create a Protection Profiles for both upload/download
+
+- [Upload documentation](https://documentation.island.io/docs/create-and-configure-an-upload-protection-profile)
+- [Download documentation](https://documentation.island.io/v1/docs/en/create-and-configure-a-download-protection-profile)
+
+1. [Create a Policy Rule](https://documentation.island.io/docs/create-and-configure-a-policy-rule-general)
+   to apply the Protection Profiles
+
+1. Define the Coder Application group as the Destination Object
+
+1. Define the applicable Protection Profile as the Action in the Data Protection
+   section
+
+### Scan files for sensitive data
+
+1. [Create a Data Loss Prevention scanner](https://documentation.island.io/docs/create-a-data-loss-prevention-scanner)
+
+1. [Create a Policy Rule](https://documentation.island.io/docs/create-and-configure-a-policy-rule-general)
+   to apply the DLP Scanner
+
+1. Define the Coder Application group as the Destination Object
+
+1. Define the DLP Scanner as the Action in the Data Protection section
+
+## Application Awareness and Boundaries
+
+Ensure that Coder is only accessed through the Island browser, guaranteeing that
+your browser-level DLP policies are always enforced, and developers can’t
+sidestep such policies simply by using another browser.
+
+### Configure browser enforcement, conditional access policies
+
+1. Create a conditional access policy for your configured identity provider.
+
+> Note: the configured IdP must be the same for both Coder and Island
+
+- [Azure Active Directory/Entra ID](https://documentation.island.io/docs/configure-browser-enforcement-for-island-with-azure-ad#create-and-apply-a-conditional-access-policy)
+- [Okta](https://documentation.island.io/docs/configure-browser-enforcement-for-island-with-okta)
+- [Google](https://documentation.island.io/docs/configure-browser-enforcement-for-island-with-google-enterprise)
+
+## Browser Activity Logging
+
+Govern and audit in-browser terminal and IDE sessions using Island, such as
+screenshots, mouse clicks, and keystrokes.
+
+### Activity Logging Module
+
+1. [Create an Activity Logging Profile](https://documentation.island.io/docs/create-and-configure-an-activity-logging-profile)
+
+Supported browser events include:
+
+- Web Navigation
+- File Download
+- File Upload
+- Clipboard/Drag & Drop
+- Print
+- Save As
+- Screenshots
+- Mouse Clicks
+- Keystrokes
+
+1. [Create a Policy Rule](https://documentation.island.io/docs/create-and-configure-a-policy-rule-general)
+   to apply the Activity Logging Profile
+
+1. Define the Coder Application group as the Destination Object
+
+1. Define the Activity Logging Profile as the Action in the Security &
+   Visibility section
+
+## Identity-aware logins (SSO)
+
+Integrate Island's identity management system with Coder's authentication
+mechanisms to enable identity-aware logins.
+
+### Configure single sign-on (SSO) seamless authentication between Coder and Island
+
+Configure the same identity provider (IdP) for both your Island and Coder
+deployment. Upon initial login to the Island browser, the user's session token
+will automatically be passed to Coder and authenticate their Coder session.
diff --git a/docs/admin/integrations/prometheus.md b/docs/admin/integrations/prometheus.md
@@ -108,7 +108,7 @@ spec:
 | `coderd_agentstats_connection_count`                          | gauge     | The number of established connections by agent                                                                                   | `agent_name` `username` `workspace_name`                                            |
 | `coderd_agentstats_connection_median_latency_seconds`         | gauge     | The median agent connection latency                                                                                              | `agent_name` `username` `workspace_name`                                            |
 | `coderd_agentstats_rx_bytes`                                  | gauge     | Agent Rx bytes                                                                                                                   | `agent_name` `username` `workspace_name`                                            |
-| `coderd_agentstats_session_count_jetbrains`                   | gauge     | The number of session established by JetBrains                                                                                   | `agent_name` `username` `workspace_name`                                            |
+| `coderd_agentstats_session_count_JetBrains`                   | gauge     | The number of session established by JetBrains                                                                                   | `agent_name` `username` `workspace_name`                                            |
 | `coderd_agentstats_session_count_reconnecting_pty`            | gauge     | The number of session established by reconnecting PTY                                                                            | `agent_name` `username` `workspace_name`                                            |
 | `coderd_agentstats_session_count_ssh`                         | gauge     | The number of session established by SSH                                                                                         | `agent_name` `username` `workspace_name`                                            |
 | `coderd_agentstats_session_count_vscode`                      | gauge     | The number of session established by VSCode                                                                                      | `agent_name` `username` `workspace_name`                                            |