EspoCRM

This guide explains how to connect EspoCRM (open-source CRM) to VaultysHub with its integrated OpenID Connect (authorization code flow, PKCE).

Prerequisites

• EspoCRM 8 or newer (tested with EspoCRM 10), served over HTTPS (for example https://crm.example.com)
• Administrator access to EspoCRM and VaultysHub

Configuration in VaultysHub

1. Applications → Add: name EspoCRM, URL https://crm.example.com/
2. Type OIDC, then:
   • Redirect URI: https://crm.example.com/oauth-callback.php
   • Allowed Scope: openid, email, profile
   • Subject Identifier (sub): Email Address
   • Require PKCE: can be enabled
3. Note the Client ID ([appid]) and the Client Secret, then assign the application to the relevant users.

EspoCRM sends the secret in the request body (client_secret_post).

Configuration in EspoCRM

Administration → Authentication → method OIDC:

Field	Value
Client ID / Client Secret	those of the VaultysHub application
Authorization Endpoint	https://your-vaultyshub.link.vaultys.org/api/oidc/[appid]/auth
Token Endpoint	https://your-vaultyshub.link.vaultys.org/api/oidc/[appid]/token
JSON Web Key Set Endpoint	https://your-vaultyshub.link.vaultys.org/api/oidc/[appid]/jwks
UserInfo Endpoint	https://your-vaultyshub.link.vaultys.org/api/oidc/[appid]/userinfo
JWT Signing Algorithms	RS256
Scopes	email, profile (EspoCRM adds openid itself)
Username Claim	email
Create User / Sync	as needed
Allow OIDC login for admin users	as needed
Fallback login	yes, to keep the administrator password login
Logout URL	https://your-vaultyshub.link.vaultys.org/api/oidc/[appid]/logout (optional)

Ensure that the Authorization Redirect URI displayed by EspoCRM matches the one declared in VaultysHub. If it does not, correct the Site URL (siteUrl) in EspoCRM.

Button Label

With OIDC, EspoCRM replaces the form with a single Log In button. The link below redisplays the password form (fallback login). To display Log In with VaultysHub, add a custom translation custom/Espo/Custom/Resources/i18n/en_US/Global.json:

{ "signInLabels": { "Oidc": "Log In with VaultysHub" } }

then clear the cache (Administration → Clear Cache).

Test

Click the login button: VaultysHub opens in a popup window. Validate with your VaultysID, the window closes, and you are logged in.

Troubleshooting

• Nothing opens: the browser blocks popups from the site.
• The button does nothing, with a JavaScript error: the scopes or JWT algorithms have been saved as text and not as a list. This happens when they are set via an environment variable of the Docker image (ESPOCRM_CONFIG_*, type auto). Set them in the interface, or with bin/command config:set oidcScopes '["email","profile"]' --type=json.
• Users without rights: VaultysHub does not pass groups; assign roles and teams in EspoCRM.

Resources

• EspoCRM Documentation — OIDC