Authenticating users with an external provider with OAuth2 and OpenID¶
Lime CRM can be configured to enable authentication using any external provider that supports an authentication flow through OAuth2 and OpenID Connect.
Note
This does not automatically create users or their appropriate groups and access privileges. It merely handles authentication, i.e. logging in.

Requirements¶
- An external authentication provider that supports OAuth2 and OpenID. This has been successfully tested with Auth0 and Okta, but it should work with other providers as well
- The users must already exist in the Lime database and their usernames must match the email addresses in the external provider, because that is how the users will be matched during authentication
Provider Configuration¶
The external providers validate that an authorization token is created for a trusted endpoint and verify that the user is not redirected somewhere they should not. For this reason the redirect URL needs to be configured in the provider. This setting can be called callback URL in some providers.
The scopes we request and need to be permitted by the provider
are openid, email, and profile. They do not normally require any
manual configuration since they are often enabled by default.
This configuration can be managed in Lime Admin (Lime Admin > System > Security > Authentication, select Open ID).
The redirect URL to Lime CRM is found on this page as Redirect URI.
Lime Configuration Structure¶
This section covers the raw configuration structure for OpenID Connect authentication in Lime CRM. Each configuration field and option is described in detail in the sections that follow.
By pointing Lime CRM to your provider's metadata document by setting the metadata_url, Lime CRM will discover the endpoints and everything else it needs automatically. This is called metadata discovery and is the recommended way to set up the OpenID configuration.
Configuring the endpoints manually with base_url and endpoint paths is deprecated and kept for backwards compatibility only. See Configuration with manual endpoints (deprecated).
Changed behavior
The following has been changed in lime-crm v3.99.0:
base_urlis no longer required whenmetadata_urlis set, and the two ways can no longer be combined- Manual endpoints are deprecated in favor of metadata discovery
- The endpoint paths are now always appended to the end of the base URL, even when they are written with a leading slash (
/) - URLs and paths are now validated, and invalid values are rejected when the configuration is saved in Lime Admin
- Changing
metadata_url,base_url, or any of the endpoint paths in Lime Admin now requires entering the client secret again
Configuration with metadata discovery (recommended)¶
Compared to manual endpoints, metadata discovery gives you:
- Simplicity: One URL is all it takes. The endpoints are discovered from what the provider publishes, so there are no paths to get wrong, and they stay correct if the provider changes them
- Single sign-out: The provider's end session endpoint is only available through the metadata document. Logging out of Lime CRM then also ends the session at the provider — with manual endpoints, only the Lime CRM session ends
- Token validation: The provider's token signing keys are fetched through the metadata document and used to verify that the tokens really come from your provider
- Faster logins: User information can be read directly from the verified token, instead of always being fetched with an extra request to the provider
{
"<solution-name>_config": {
"authentication": {
"provider": "openid",
"openid": {
"metadata_url": "https://<provider-domain>/.well-known/openid-configuration",
"client_id": "<your_client_id>",
"client_secret_expiration_date": "2026-12-31",
"forced_username_password": false
}
}
},
"<solution-name>_secrets": {
"authentication": {
"openid": {
"client_secret": "<your_client_secret_value>"
}
}
}
}
<solution-name>:
config:
authentication:
provider: openid
openid:
metadata_url: https://<provider-domain>/.well-known/openid-configuration
client_id: <your_client_id>
client_secret_expiration_date: "2026-12-31"
forced_username_password: false
secrets:
authentication:
openid:
client_secret: <your_client_secret_value>
Configuration with manual endpoints (deprecated)¶
Deprecated
Manual endpoints are deprecated. Use metadata discovery instead. Existing configurations keep working, but switch to metadata_url when you get the chance.
metadata_url cannot be combined with base_url or the endpoint paths. A configuration that mixes the two ways is rejected when saved in Lime Admin.
Show the deprecated manual endpoint configuration
If your provider does not publish a metadata document, the endpoints can be configured manually with the following fields:
base_url(string): The base URL the endpoint paths are appended to. It may include a path of its own, for examplehttps://example.com/oauth2access_token_path(string): The path of the token endpoint, appended to the base URLauthorize_path(string): The path of the authorization endpoint, appended to the base URLuser_info_path(string, optional): The path of the user info endpoint, appended to the base URL. Defaults to/userinfo
base_url, access_token_path, and authorize_path are required.
The endpoint paths are appended to the end of the base URL. It makes no difference whether a path is written with or without a leading slash (/), and a trailing slash at the end of the base URL is ignored:
base_url = "https://example.com/lime/oauth2"
access_token_path = "/access_token"
authorize_path = "/authorize"
URL to the access token endpoint = "https://example.com/lime/oauth2/access_token"
URL to the authorize endpoint = "https://example.com/lime/oauth2/authorize"
A complete configuration with manual endpoints looks like this:
{
"<solution-name>_config": {
"authentication": {
"provider": "openid",
"openid": {
"base_url": "https://<provider-domain-base-url>",
"client_id": "<your_client_id>",
"client_secret_expiration_date": "2026-12-31",
"forced_username_password": false,
"access_token_path": "/token",
"authorize_path": "/authorize",
"user_info_path": "/userinfo"
}
}
},
"<solution-name>_secrets": {
"authentication": {
"openid": {
"client_secret": "<your_client_secret_value>"
}
}
}
}
<solution-name>:
config:
authentication:
provider: openid
openid:
base_url: https://<provider-domain-base-url>
client_id: <your_client_id>
client_secret_expiration_date: "2026-12-31"
forced_username_password: false
access_token_path: /token
authorize_path: /authorize
user_info_path: /userinfo
secrets:
authentication:
openid:
client_secret: <your_client_secret_value>
Configuration Fields¶
Required Fields¶
client_id(string): The client ID provided by your OpenID Connect provider during application registrationclient_secret(string): The client secret provided by your provider (stored in secrets section)
Authentication Behavior¶
-
forced_username_password(boolean, default: false): Allows bypassing OpenID login with Lime username/passwordWarning
Only use this temporarily for troubleshooting
Provider Endpoints¶
metadata_url(string): The URL of the provider's metadata document. All endpoints are discovered from itbase_url,access_token_path,authorize_path,user_info_path(deprecated): Manual endpoint configuration, described under Configuration with manual endpoints (deprecated)
Validation¶
The URLs and paths are validated:
base_urlandmetadata_urlmust be absolute URLs starting withhttp://orhttps://access_token_path,authorize_path, anduser_info_pathmust be plain paths, without a scheme, host, query, or fragment
Invalid values are rejected when the configuration is saved in Lime Admin. If a configuration file contains invalid values, the configuration does not load and users cannot log in until the values are corrected.
Client Secret Management¶
client_secret_expiration_date(date, optional): When the client secret expires (format: "YYYY-MM-DD"). Used for monitoring and alerts
Changing endpoints requires the client secret
The client secret is never shown in Lime Admin, and leaving the field empty when saving keeps the already saved secret. Changing metadata_url, base_url, or any of the endpoint paths requires entering the client secret again, since a secret is only valid for the provider it was issued by.
Provider-Specific URLs
Most providers publish their metadata document at /.well-known/openid-configuration under their domain.
For example:
- Auth0:
https://your-domain.auth0.com/.well-known/openid-configuration - Okta:
https://your-domain.okta.com/.well-known/openid-configuration
Check your provider's documentation for the exact metadata URL.
Examples¶
The following examples show configuration settings for popular external OpenID Connect providers.
These configurations can serve as templates for these providers or when setting up authentication with similar providers.
Configuration for Auth0¶
{
"<solution-name>_config": {
"authentication": {
"provider": "openid",
"openid": {
"metadata_url": "https://<your_auth0_domain>.auth0.com/.well-known/openid-configuration",
"client_id": "<your_auth0_client_id>"
}
}
},
"<solution-name>_secrets": {
"authentication": {
"openid": {
"client_secret": "<your_client_secret_value>"
}
}
}
}
Configuration for Okta¶
{
"<solution-name>_config": {
"authentication": {
"provider": "openid",
"openid": {
"metadata_url": "https://<your_okta_domain>.okta.com/.well-known/openid-configuration",
"client_id": "<your_okta_client_id>"
}
}
},
"<solution-name>_secrets": {
"authentication": {
"openid": {
"client_secret": "<your_client_secret_value>"
}
}
}
}
Common Pitfalls¶
Base URL¶
If the base URL is not properly configured the authentication flow might work, but redirecting the user back to Lime CRM will most likely fail.
HTTP/HTTPS Misconfiguration¶
During testing the redirect URL will most likely use HTTP (http://...) and 127.0.0.1 or
localhost. Always ensure HTTPS (https://...) is used in production environments to
secure sensitive data and prevent man-in-the-middle attacks.
If the base URL is configured with a protocol that is not supported
the authentication will fail.
Missing User In Lime Database¶
The user in the Lime database and the user trying to log in need to have the same email address in the external provider as the username in Lime CRM. Otherwise the user will not be able to log in.