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. Below is a complete example showing what the configuration might look like with all available options. Each configuration field and option is described in detail in the sections that follow.

Lime CloudOn-Premise

{
  "<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",
        "metadata_url": "<your_metadata_url>"
      }
    }
  },
  "<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
        metadata_url: <your_metadata_url>
  secrets:
    authentication:
      openid:
        client_secret: <your_client_secret_value>

Configuration Fields¶

Required Fields¶

base_url (string): The base URL of your OpenID Connect provider. This is the common URL for user redirects and server-to-server requests
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, optional): The URL for metadata requests
access_token_path (string, optional): The path for token exchange requests
authorize_path (string, optional): The path for authorization requests
user_info_path (string, optional): The path for user info requests

Endpoint Configuration Requirements

When metadata_url is specified, Lime CRM will automatically discover the required endpoints from the provider's metadata. This means that only metadata_url is required.

If metadata_url is not specified, both access_token_path and authorize_path are required, user_info_path is always optional and overrides the discovered value.

Warning

Make sure the values of access_token_path, authorize_path and user_info_path does not start with a forward slash (/).
If a value start with / it will be added to the root of the base_url instead of at the end, most likely resulting in the wrong URL.

Example:

base_url = "https://example.com/lime/oauth2"
access_token_path = "access_token"
authorize_path = "/authorize"

URL to access token endpoint = "https://example.com/lime/oauth2/access_token" ✅
URL to authorize endpoint = "https://example.com/authorize" ❌

Client Secret Management¶

client_secret_expiration_date (date, optional): When the client secret expires (format: "YYYY-MM-DD"). Used for monitoring and alerts

Provider-Specific URLs

Different providers may use different URL structures.

For example:

Auth0: https://your-domain.auth0.com
Okta: https://your-domain.okta.com/oauth2/v1/

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¶

Lime CloudOn-Premise

{
  "<solution-name>_config": {
    "authentication": {
      "provider": "openid",
      "openid": {
        "base_url": "https://<your_auth0_domain>.auth0.com",
        "access_token_path": "token",
        "authorize_path": "authorize",
        "client_id": "<your_auth0_client_id>"
      }
    }
  },
  "<solution-name>_secrets": {
    "authentication": {
      "openid": {
        "client_secret": "<your_client_secret_value>"
      }
    }
  }
}

<solution-name>:
  config:
    authentication:
      provider: openid
      openid:
        base_url: https://<your_auth0_domain>.auth0.com
        access_token_path: token
        authorize_path: authorize
        client_id: <your_auth0_client_id>
  secrets:
    authentication:
      openid:
        client_secret: <your_client_secret_value>

Configuration for Okta¶

The main difference for Okta compared to Auth0 is that there are additional paths in the base URL. This may apply to some other vendors as well.

Lime CloudOn-Premise

{
  "<solution-name>_config": {
    "authentication": {
      "provider": "openid",
      "openid": {
        "base_url": "https://<your_okta_domain>.okta.com/oauth2/v1/",
        "access_token_path": "token",
        "authorize_path": "authorize",
        "client_id": "<your_okta_client_id>"
      }
    }
  },
  "<solution-name>_secrets": {
    "authentication": {
      "openid": {
        "client_secret": "<your_client_secret_value>"
      }
    }
  }
}

<solution-name>:
  config:
    authentication:
      provider: openid
      openid:
        base_url: https://<your_okta_domain>.okta.com/oauth2/v1/
        access_token_path: token
        authorize_path: authorize
        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.