website/integrations: add espoCRM

website/integrations/services/espoCRM/index.md

@@ -0,0 +1,78 @@
+---
+title: Integrate with EspoCRM
+sidebar_label: EspoCRM
+---
+
+# EspoCRM
+
+<span class="badge badge--secondary">Support level: Community</span>
+
+## What is EspoCRM?
+
+> EspoCRM is a CRM (customer relationship management) web application that allows users to store, visualize, and analyze their company's business-related relationships such as opportunities, people, businesses, and projects. 
+>
+> -- https://www.espocrm.com/
+
+:::warning
+This guide does _not_ cover Team Mapping. Please refer to EspoCRM's [documentation](https://docs.espocrm.com/administration/oidc/#team-mapping).
+:::
+
+## Preparation
+
+The following placeholders will be used:
+
+-   `crm.company` is the FQDN of the EspoCRM install. 
+-   `authentik.company` is the FQDN of the authentik install.
+- `_SLUG_` is the slug you choose upon application create in authentik.
+
+## authentik configuration
+1. Log into authentik as an admin, and navigate to **Applications** --> **Applications**.
+2. Click **Create with Wizard**.
+
+:::info
+Alternatively, use our legacy process and click **Create**. The legacy process requires that the application and its configuration provider be configured separately.
+:::
+
+3. In the _New Application_ wizard, define the application details, and then define the provider details with the following parameters:
+
+- **Provider Type**: `OAuth2/OIDC (Open Authorization/OpenID Connect)`
+
+- **Authorization Flow**: `default-provider-authorization-explicit-consent (Authorize Application)`
+- **Client Type**: `Confidential`
+- **Redirect URIs/Origins**: `https://_crm.company_/oauth-callback.php`
+- **Scopes**: OpenID, Email, Profile, Proxy outpost
+- **Subject Mode**: `Based on the User's username` (**OR** your preferred method; you can use the same username in authentik and EspoCRM)
+- **Signing Key**: Select any available key
+
+Note the `Client ID` and `Client Secret` values. 
+
+## EspoCRM configuration
+### Access the OIDC auth
+1. Login to your admin user at `crm.company`.
+
+2. In EspoCRM at Administration > Authentication, select the OIDC method. Below, on the same form, a OIDC panel will appear.
+
+### Configure the OIDC auth
+1. Configure the following variables:
+- **Client ID**: enter the `Client ID` from authentik
+- **Client Secret**: enter the `Client Secret` from authentik 
+- **Authorization Redirect URI**: `https://_crm.company_/oauth-callback.php`
+- **Fallback Login**: _Select this option if you want EspoCRM's login as fallback._
+- **Allow OIDC login for admin users**: _Select this option if you want EspoCRM's admin users to be able to log in via OIDC._
+
+    _The following values I listed as slugs for clarity. I included an example for the first variable.
+The full URLs can also be found on the provider's page in authentik's UI._
+
+- **Authorization Endpoint**: `/application/o/authorize/`
+    - (e.g. `https://_crm.company_/application/o/authorize/`)
+- **Token Endpoint**: `/application/o/token/`
+- **JSON Web Key Set Endpoint**: `/application/o/_SLUG_/jwks/`
+- **Logout URL**: `application/o/_SLUG_/end-session/`
+
+### Confirm the configuration 
+1. Select the `Save` option.
+
+2. Access `crm.company` in a private browser, and select `Sign In.`
+- You will be presented with your authentik log-in screen.
+
+- Enter your authentik credentials to proceed to EspoCRM!

website/sidebarsIntegrations.js

@@ -27,6 +27,7 @@ module.exports = {
                     items: [
                         "services/bookstack/index",
                         "services/dokuwiki/index",
+                        "services/espoCRM/index",
                         "services/hedgedoc/index",
                         "services/kimai/index",
                         "services/mastodon/index",