Skip to content

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.

OpenID Connect authentication flow diagram showing interaction between user, Lime CRM, and external provider

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_url is no longer required when metadata_url is 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

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 example https://example.com/oauth2
  • access_token_path (string): The path of the token endpoint, appended to the base URL
  • authorize_path (string): The path of the authorization endpoint, appended to the base URL
  • user_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 registration
  • client_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/password

    Warning

    Only use this temporarily for troubleshooting

Provider Endpoints

  • metadata_url (string): The URL of the provider's metadata document. All endpoints are discovered from it
  • base_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_url and metadata_url must be absolute URLs starting with http:// or https://
  • access_token_path, authorize_path, and user_info_path must 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>"
      }
    }
  }
}
<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>
  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>"
      }
    }
  }
}
<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>
  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.