Using OIDC to connect to Microsoft Entra ID

[bandtank]

This guide is intended to help developers and administrators connect an EspoCRM instance to Microsoft Entra ID through the built-in OIDC authorization process.

---

Entra ID exposes OpenID Connect (OIDC) endpoints, which EspoCRM can natively use. The following links should be used during the implementation process:

1. EspoCRM OIDC Documentation
2. Microsoft OpenID Connect Documentation
3. Microsoft ID Token Claims Reference
4. Forum post about the JWKS URI

Before beginning this process, be sure to set the username field for the users in your system to a value that matches something in Microsoft Entra ID. For most organizations, the primary UPN in Microsoft Entra ID will be the email address, which means the username field for each user in EspoCRM should contain the user's email address. It is possible to use other values, but this guide assumes the email address will be used as the identifying string in both systems.

---

Step 1

Reference: Link 1

Begin the process by navigating in EspoCRM to Administration -> Authentication. Make the following changes:

• Authorization Method: OIDC
• Enable 2-Factor Authentication: False (2FA must be handled by Entra ID. Espo's native 2FA will not work when OIDC is enabled).
• Any other relevant settings for your organization regarding general authentication settings

---

Step 2

Reference: Link 1

Create a new App Registration in Microsoft Entra Admin Center:




Set the configuration as follows:

• Give the application a name
• Set the account type (the first option is most likely what you want)
• Add a new Web redirect URI with the value from EspoCRM in Administration -> Authentication -> OIDC -> Authorization Redirect URI:

---

Step 3

Reference: Link 1

Copy the Client ID (it is called Application (client) ID in Entra Admin Center). Paste it into EspoCRM in Administration -> Authentication -> OIDC -> Client ID:

---

Step 4

Reference: Link 1

Create a new secret for the application. Set the expiration to whichever value makes the most sense for you (I always choose 24 months and then set a reminder to renew the secret two weeks before the expiration date):

[bandtank]

Step 4 continued:

Copy the Value (not the Secret ID). Paste it into EspoCRM in Administration -> Authentication -> OIDC -> Client Secret:

---

Step 5

Reference: Links 1 and 2

Set the appropriate permissions and grant admin consent. The permissions are:

• Microsoft Graph - Delegated - email
• Microsoft Graph - Delegated - openid
• Microsoft Graph - Delegated - profile
• Microsoft Graph - Delegated - User.Read

---

Step 6

Reference: Links 1, 2, and 4

Copy the endpoints for Authorization, Token, and JSON Web Key Set. The first two values can be found in Entra Admin Center -> Applications -> App Registrations -> Endpoints:



The JSON Web Key Set value is https://login.microsoftonline.com/common/discovery/v2.0/keys.

---

Step 7

Reference: Link 1

Finish configuring EspoCRM's OIDC settings. The following notes should help:

• Scopes - Set this for your organization's needs. The default values of profile, email, and phone are probably fine for most configurations.
• Username Claim - See Link 3. sub is the default value, but that is probably not correct for Microsoft Entra ID's connection to your organization. You most likely want to use email.
• Create User - Set this value to True if you want EspoCRM to create a user if one does not exist after a successful authentication with Microsoft Entra ID through OIDC.
• Sync - Allow EspoCRM to update the user's profile with information from Microsoft Entra ID each time a successful login occurs.
• Teams - I have not experimented with this, so I do not know how it works yet.
• Group Claim - I have not experimented with this, so I do not know how it works yet.
• Sync Teams - I have not experimented with this, so I do not know how it works yet.
• Fallback Login - Allow EspoCRM to internally authenticate users if OIDC fails.
• Allow fallback login for regular users: If regular users fail to authenticate with OIDC and this value is set to True, EspoCRM will allow users to authenticate internally.
• Allow OIDC login for admin users: By default, admin users must authenticate internally. Setting this value to True allows admin users to authenticate with Microsoft Entra ID through OIDC.
• Authorization Prompt - More on this in step 8.

---

Step 8

Reference: Links 1 and 2

Set the consent field. Neither the Microsoft Entra ID documentation nor the EspoCRM documentation give much information about what this field does, so here is my best guess:

• none - No consent is offered (or needed?).
• login - Logging in successfully provides user consent. This is the option I use because my users don't need to deal with this part of the process.
• consent - The user must click a checkbox to provide consent. Unfortunately, the consent form pops up every time in my experience, so I do not use this option.
• select_account - I do not know because I haven't tried it.

When login is used, successful logins take users straight to the EspoCRM dashboard. When consent is used, users will see the following form:

[yuri]

Here's explanation of the "consent" in the OIDC specification. After a few paragraphs down the text. https://openid.net/specs/openid-conn...ml#AuthRequest

Note that OIDC authentication in EspoCRM is an implementation of the standard. Different provider often work differently and require specific configuration. I remember that one provider required a specific consent value, otherwise it didn't authenticate.

[bandtank]

Thanks for the information. That is very helpful.

[bandtank]

Step 9

Log in to the application. The login screen will change to the following form:



If the fallback method is enabled, the down arrow and associated form will also be available:

[esforim]

Don't think I will ever need this but compliment to the goodtank.

[bandtank]

Thank you!