Merge branch 'main' into chore/2415-sentry-keep-ui

# Conflicts: # keep-ui/package-lock.json
keephq · Nov 12, 2024 · e6b3b7c · e6b3b7c
2 parents 832158f + b6894fd
commit e6b3b7c
Show file tree

Hide file tree

Showing 124 changed files with 5,549 additions and 5,294 deletions.
diff --git a/docs/deployment/authentication/azuread-auth.mdx b/docs/deployment/authentication/azuread-auth.mdx
@@ -0,0 +1,202 @@
+---
+title: "Azure AD Authentication"
+---
+
+<Tip>
+This feature is a part of Keep Enterprise.
+
+Talk to us to get access: https://www.keephq.dev/meet-keep
+</Tip>
+
+Keep supports enterprise authentication through Azure Active Directory (Azure AD), enabling organizations to use their existing Microsoft identity platform for secure access management.
+
+## When to Use
+
+- **Microsoft Environment:** If your organization uses Microsoft 365 or Azure services, Azure AD integration provides seamless authentication.
+- **Enterprise SSO:** Leverage Azure AD's Single Sign-On capabilities for unified access management.
+
+## Setup Instructions (on Azure AD)
+
+### Creating an Azure AD Application
+
+1. Sign in to the [Azure Portal](https://portal.azure.com)
+2. Navigate to **Microsoft Entra ID** > **App registrations** > **New registration**
+
+<Frame>
+  <img src="/images/azuread_1.png" width="1000" alt="Azure AD App Registration"/>
+</Frame>
+
+3. Configure the application:
+   - Name: "Keep"
+
+<Info>Note that we are using "Register an application to integrate with Microsoft Entra ID (App you're developing)" since you're self-hosting Keep and need direct control over the authentication flow and permissions for your specific instance - unlike the cloud/managed version where Keep's team has already configured a centralized application registration.</Info>
+
+<Frame>
+  <img src="/images/azuread_2.png" width="1000" alt="Azure AD App Registration"/>
+</Frame>
+
+4. Configure the application (continue)
+- Supported account types: "Single tenant"
+
+<Info>
+We recommend using "Single tenant" for enhanced security as it restricts access to users within your organization only. While multi-tenant configuration is possible, it would allow users from any Azure AD directory to access your Keep instance, which could pose security risks unless you have specific cross-organization requirements.
+</Info>
+
+    - Redirect URI: "Web" + your redirect URI
+
+<Info>
+We use "Web" platform instead of "Single Page Application (SPA)" because Keep's backend handles the authentication flow using client credentials/secrets, which is more secure than the implicit flow used in SPAs. This prevents exposure of tokens in the browser and provides stronger security through server-side token validation and refresh token handling.
+</Info>
+
+<Tip>
+For localhost, the redirect would be http://localhost:3000/api/auth/callback/azure-ad
+
+For production, it should be something like http://your_keep_frontend_domain/api/auth/callback/azure-ad
+
+</Tip>
+
+<Frame>
+  <img src="/images/azuread_3.png" width="1000" alt="Azure AD App Registration"/>
+</Frame>
+
+5. Finally, click "register"
+
+### Configure Authentication
+After we created the application, let's configure the authentication.
+
+1. Go to "App Registrations" -> "All applications"
+
+<Frame>
+  <img src="/images/azuread_4.png" width="1000" alt="Azure AD Authentication Configuration"/>
+</Frame>
+
+
+2. Click on your application -> "Add a certificate or secret"
+
+<Frame>
+  <img src="/images/azuread_5.png" width="1000" alt="Azure AD Authentication Configuration"/>
+</Frame>
+
+
+3. Click on "New client secret" and give it a name
+
+<Frame>
+  <img src="/images/azuread_6.png" width="1000" alt="Azure AD Authentication Configuration"/>
+</Frame>
+
+4. Keep the "Value", we will use it soon as `KEEP_AZUREAD_CLIENT_SECRET`
+
+<Frame>
+  <img src="/images/azuread_7.png" width="1000" alt="Azure AD Authentication Configuration"/>
+</Frame>
+
+### Configure Groups
+
+Keep maps Azure AD groups to roles with two default groups:
+1. Admin Group (read + write)
+2. NOC Group (read only)
+
+To create those groups, go to Groups -> All groups and create two groups:
+
+<Frame>
+  <img src="/images/azuread_16.png" width="1000" alt="Azure AD Authentication Configuration"/>
+</Frame>
+
+Keep the Object id of these groups and use it as `KEEP_AZUREAD_ADMIN_GROUP_ID` and `KEEP_AZUREAD_NOC_GROUP_ID`.
+
+### Configure Group Claims
+
+1. Navigate to **Token configuration**
+
+<Frame>
+  <img src="/images/azuread_8.png" width="1000" alt="Azure AD Authentication Configuration"/>
+</Frame>
+
+
+2. Add groups claim:
+   - Select "Security groups" and "Groups assigned to the application"
+   - Choose "Group ID" as the claim value
+
+<Frame>
+  <img src="/images/azuread_9.png" width="1000" alt="Azure AD Authentication Configuration"/>
+</Frame>
+
+
+<Frame>
+  <img src="/images/azuread_10.png" width="1000" alt="Azure AD Authentication Configuration"/>
+</Frame>
+
+### Configure Application Scopes
+
+1. Go to "Expose an API" and click on "Add a scope"
+
+<Frame>
+  <img src="/images/azuread_11.png" width="1000" alt="Azure AD Authentication Configuration"/>
+</Frame>
+
+2. Keep the default Application ID and click "Save and continue"
+
+<Frame>
+  <img src="/images/azuread_12.png" width="1000" alt="Azure AD Authentication Configuration"/>
+</Frame>
+
+3. Add "default" as scope name, also give a display name and description
+
+<Frame>
+  <img src="/images/azuread_13.png" width="1000" alt="Azure AD Authentication Configuration"/>
+</Frame>
+
+3. Finally, click "Add scope"
+
+<Frame>
+  <img src="/images/azuread_14.png" width="1000" alt="Azure AD Authentication Configuration"/>
+</Frame>
+
+## Setup Instructions (on Keep)
+
+After you configured Azure AD you should have the following:
+1. Azure AD Tenant ID
+2. Azure AD Client ID
+
+How to get:
+
+<Frame>
+  <img src="/images/azuread_15.png" width="1000" alt="Azure AD Authentication Configuration"/>
+</Frame>
+
+3. Azure AD Client Secret [See Configure Authentication](#configure-authentication).
+4. Azure AD Group ID's for Admins and NOC (read only) [See Configure Groups](#configure-groups).
+
+
+### Configuration
+
+#### Frontend
+
+| Environment Variable | Description | Required | Default Value |
+|--------------------|-------------|:---------:|:-------------:|
+| AUTH_TYPE | Set to 'AZUREAD' for Azure AD authentication | Yes | - |
+| KEEP_AZUREAD_CLIENT_ID | Your Azure AD application (client) ID | Yes | - |
+| KEEP_AZUREAD_CLIENT_SECRET | Your client secret | Yes | - |
+| KEEP_AZUREAD_TENANT_ID | Your Azure AD tenant ID | Yes | - |
+| NEXTAUTH_URL | Your Keep application URL | Yes | - |
+| NEXTAUTH_SECRET | Random string for NextAuth.js | Yes | - |
+
+#### Backend
+
+| Environment Variable | Description | Required | Default Value |
+|--------------------|-------------|:---------:|:-------------:|
+| AUTH_TYPE | Set to 'AZUREAD' for Azure AD authentication | Yes | - |
+| KEEP_AZUREAD_TENANT_ID | Your Azure AD tenant ID | Yes | - |
+| KEEP_AZUREAD_CLIENT_ID | Your Azure AD application (client) ID | Yes | - |
+| KEEP_AZUREAD_ADMIN_GROUP_ID | The group ID of Keep Admins (read write) | Yes | - |
+| KEEP_AZUREAD_NOC_GROUP_ID | The group ID of Keep NOC (read only) | Yes | - |
+
+## Features and Limitations
+
+#### Supported Features
+- Single Sign-On (SSO)
+- Role-based access control through Azure AD groups
+- Multi-factor authentication (when configured in Azure AD)
+
+#### Limitations
+See [Overview](/deployment/authentication/overview)
diff --git a/docs/deployment/authentication/overview.mdx b/docs/deployment/authentication/overview.mdx
@@ -13,6 +13,7 @@ Keep supports various authentication providers and architectures to accommodate
 - [**DB**](/deployment/authentication/db-auth) - Simple username/password authentication. Works well for small teams or for dev/stage environments. Users and hashed password are stored on DB.
 - [**Auth0**](/deployment/authentication/auth0-auth) - Utilize Auth0 for scalable, auth0-based authentication.
 - [**Keycloak**](/deployment/authentication/keycloak-auth) - Utilize Keycloak for enterprise authentication methods such as SSO/SAML/OIDC, advanced RBAC with custom roles, resource-level permissions, and integration with user directories (LDAP).
+- [**AzureAD**](/deployment/authentication/azuread-auth) - Utilize Azure AD for SSO/SAML/OIDC nterprise authentication.
 
 Choosing the right authentication strategy depends on your specific use case, security requirements, and deployment environment. You can read more about each authentication provider.
 
@@ -27,6 +28,7 @@ Choosing the right authentication strategy depends on your specific use case, se
 | **Auth0**             |  ✅ <br />(Predefiend roles)  |     ✅     |  🚧  |             🚧            |        ✅        |         🚧        |    ❌    |   **EE**   |
 | **Keycloak**          |  ✅ <br />(Custom roles)  |     ✅     |  ✅   |             ✅            |        ✅        |         ✅         |    ✅    |   **EE**    |
 | **Oauth2Proxy**       |  ✅ <br />(Predefiend roles)  |     ✅     |  ❌   |             ❌            |        N/A        |         N/A         |    ✅    |   **OSS**   |
+| **Azure AD**       |  ✅ <br />(Predefiend roles)  |     ✅     |  ❌   |             ❌            |        By Azure AD        |         By Azure AD         |    ✅    |   **EE**   |
 ### How To Configure
 <Tip>
 Some authentication providers require additional environment variables. These will be covered in detail on the specific authentication provider pages.
@@ -41,5 +43,6 @@ The authentication scheme on Keep is controlled with environment variables both
 | **Auth0**                           |  `AUTH_TYPE=AUTH0`  | `AUTH0_DOMAIN`, `AUTH0_CLIENT_ID`, `AUTH0_CLIENT_SECRET` |
 | **Keycloak** | `AUTH_TYPE=KEYCLOAK` | `KEYCLOAK_URL`, `KEYCLOAK_REALM`, `KEYCLOAK_CLIENT_ID`, `KEYCLOAK_CLIENT_SECRET` |
 | **Oauth2Proxy** | `AUTH_TYPE=OAUTH2PROXY` | `OAUTH2_PROXY_USER_HEADER`, `OAUTH2_PROXY_ROLE_HEADER`, `OAUTH2_PROXY_AUTO_CREATE_USER` |
+| **AzureAD** | `AUTH_TYPE=AZUREAD` | See [AzureAD Configuration](/deployment/authentication/azuread-auth) |
 
 For more details on each authentication strategy, including setup instructions and implications, refer to the respective sections.
diff --git a/docs/images/azuread_1.png b/docs/images/azuread_1.png
diff --git a/docs/images/azuread_10.png b/docs/images/azuread_10.png
diff --git a/docs/images/azuread_11.png b/docs/images/azuread_11.png
diff --git a/docs/images/azuread_12.png b/docs/images/azuread_12.png
diff --git a/docs/images/azuread_13.png b/docs/images/azuread_13.png
diff --git a/docs/images/azuread_14.png b/docs/images/azuread_14.png
diff --git a/docs/images/azuread_15.png b/docs/images/azuread_15.png
diff --git a/docs/images/azuread_16.png b/docs/images/azuread_16.png
diff --git a/docs/images/azuread_2.png b/docs/images/azuread_2.png
diff --git a/docs/images/azuread_3.png b/docs/images/azuread_3.png
diff --git a/docs/images/azuread_4.png b/docs/images/azuread_4.png
diff --git a/docs/images/azuread_5.png b/docs/images/azuread_5.png
diff --git a/docs/images/azuread_6.png b/docs/images/azuread_6.png
diff --git a/docs/images/azuread_7.png b/docs/images/azuread_7.png
diff --git a/docs/images/azuread_8.png b/docs/images/azuread_8.png
diff --git a/docs/images/azuread_9.png b/docs/images/azuread_9.png
diff --git a/docs/images/connect-to-pagerduty.png b/docs/images/connect-to-pagerduty.png
diff --git a/docs/images/pagerduty-account-scope.png b/docs/images/pagerduty-account-scope.png
diff --git a/docs/images/pagerduty-app-registration.png b/docs/images/pagerduty-app-registration.png
diff --git a/docs/images/pagerduty-oauth2-credentials.png b/docs/images/pagerduty-oauth2-credentials.png
diff --git a/docs/images/pagerduty-redirect-url.png b/docs/images/pagerduty-redirect-url.png
diff --git a/docs/images/pagerduty-service-scope.png b/docs/images/pagerduty-service-scope.png
diff --git a/docs/mint.json b/docs/mint.json
@@ -64,6 +64,7 @@
             "deployment/authentication/no-auth",
             "deployment/authentication/db-auth",
             "deployment/authentication/auth0-auth",
+            "deployment/authentication/azuread-auth",
             "deployment/authentication/keycloak-auth",
             "deployment/authentication/oauth2proxy-auth"
           ]

diff --git a/docs/providers/documentation/pagerduty-provider.mdx b/docs/providers/documentation/pagerduty-provider.mdx
@@ -1,12 +1,16 @@
 ---
 title: "Pagerduty Provider"
-description: "Pagerduty Provider is a provider that allows to create incidents or post events to Pagerduty."
+description: "Pagerduty Provider allows integration with PagerDuty to create, manage, and synchronize incidents and alerts within Keep."
 ---
 
+## Description
+
+The Pagerduty Provider enables integration with PagerDuty to create, manage, and synchronize incidents and alerts within Keep. It supports both direct API key authentication and OAuth2, allowing greater flexibility for secure integration.
+
 ## Inputs
 
 - `title`: str: Title of the alert or incident.
-- `alert_body`: str: UTF-8 string of custom message for alert. Shown in incident body for events, and in the body for incidents.
+- `alert_body`: dict: https://developer.pagerduty.com/api-reference/a7d81b0e9200f-create-an-incident#request-body
 - `dedup`: str | None: Any string, max 255 characters, used to deduplicate alerts for events.
 - `service_id`: str: ID of the service for incidents.
 - `body`: dict: Body of the incident.
@@ -15,39 +19,92 @@ description: "Pagerduty Provider is a provider that allows to create incidents o
 
 ## Authentication Parameters
 
-The `api_key` or `routing_key` are required for connecting to the Pagerduty provider. You can obtain them as described in the "Connecting with the Provider" section.
+PagerDuty supports two authentication methods:
 
-Routing key, which is an integration or ruleset key. API key, which is a user or team API key.
+1. **API Key** - A user or team key, accessible through **Configuration > API Access** in PagerDuty.
+2. **OAuth2** - Supports installation with OAuth2, with access and refresh tokens managed within Keep.
 
 ## Connecting with the Provider
 
-To use the PagerdutyProvider, you'll need to provide either a routing_key or an api_key.
+To connect Keep to PagerDuty:
+
+- **Routing Key**: Use for event posting via the PagerDuty Events API.
+- **API Key**: Use for incident creation and management through the PagerDuty Incidents API.
+- **OAuth2**: Token management handled automatically by Keep.
+
+<Frame>
+  <img src="/images/connect-to-pagerduty.png" />
+</Frame>
 
+<Note>
 You can find your integration key or routing key in the PagerDuty web app under **Configuration** > **Integrations**, and select the integration you want to use.
 You can find your API key in the PagerDuty web app under **Configuration** > **API Access**.
 
-The routing_key is used to post events to Pagerduty using the events API.
+The routing_key is used to post events to PagerDuty using the events API.
 The api_key is used to create incidents using the incidents API.
 
+</Note>
+
+### Enabling OAuth in the open-source version
+
+If you would like to use OAuth in the open-source, where you self-host Keep, you can do so by following these step:
+1. Create a PagerDuty account
+2. In the account page, go to **Integrations** > **App Registration**
+<Frame>
+  <img src="/images/pagerduty-app-registration.png" />
+</Frame>
+3. Click on **New App** blue button on the top right
+4. Fill in the required fields
+5. Select "OAuth 2.0" in the Functionality section and click **Next**
+6. In the Redirect URL, you need to add Keep's PagerDuty OAuth2 redirect URL, which is based on your deployments URL. For example, if Keep is deployed at http://localhost:3000, the redirect URL is http://localhost:3000/providers/oauth2/pagerduty
+<Frame>
+  <img src="/images/pagerduty-redirect-url.png" />
+</Frame>
+7. In the Authorization section, select **Scoped OAuth** and select the following scopes:
+- Abilities: Read Access
+- Incidents: Read/Write Access
+- Services: Read/Write Access
+- Webhook Subscriptions: Read/Write Access
+8. Click on **Register App** blue button on the bottom right
+9. Copy the **Client ID** and **Client Secret** from the OAuth 2.0 Client Information modal and set the `PAGERDUTY_CLIENT_ID` and `PAGERDUTY_CLIENT_SECRET` environment variables in your Keep backend deployment.
+<Frame>
+  <img src="/images/pagerduty-oauth2-credentials.png" />
+</Frame>
+
+## PagerDuty Webhook Integration
+
+By default, when Keep installs itself as a webhook integration, it subscribes to all incident events ("Account Scope").
+
+<Frame>
+  <img src="/images/pagerduty-account-scope.png" />
+</Frame>
+
+If you wish to limit Keep to some specific services, you can do so by selecting the **Service** scope and selecting the services you want to subscribe to.
+
+<Frame>
+  <img src="/images/pagerduty-service-scope.png" />
+</Frame>
+
+Find this page under **Integrations** > **Generic Webhooks (v3)**
+
 ## Scopes
 
 Certain scopes may be required to perform specific actions or queries via the Pagerduty Provider. Below is a summary of relevant scopes and their use cases:
 
 - incidents_read (Incidents Read)
-    Required: True
-    Description: View incidents.
+  Required: True
+  Description: View incidents.
 - incidents_write (Incidents Write)
-    Required: False
-    Description: Write incidents.
+  Required: False
+  Description: Write incidents.
 - webhook_subscriptions_read (Webhook Subscriptions Read)
-    Required: False
-    Description: View webhook subscriptions.
-    (*Required for auto-webhook integration)
+  Required: False
+  Description: View webhook subscriptions.
+  (\*Required for auto-webhook integration)
 - webhook_subscriptions_write (Webhook Subscriptions Write)
-    Required: False
-    Description: Write webhook subscriptions.
-    (*Required for auto-webhook integration)
-
+  Required: False
+  Description: Write webhook subscriptions.
+  (\*Required for auto-webhook integration)
 
 ## Notes
 
@@ -59,6 +116,7 @@ An expired trial while using the free version of PagerDuty may result in the "pa
 
 The webhook integration adds Keep as a destination within the "Integrations" API within Pagerduty.
 This grants Keep access to the following scopes within Pagerduty:
+
 - `webhook_subscriptions_read`
 - `webhook_subscriptions_write`