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 that this does not automatically create users or their appropriate groups and access privileges. It merely handles authentication, i.e. logging in.

Authentication flow

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.
Users that wish to log in must already exist in the Lime database and have their username set to their email address as it appears in the external provider. The user being authenticated will automatically be logged in as a user with matching email address as their username in the Lime database.

Please make sure you have received a Redirect URL from Lime. It typically follows the format: https://[lime-server].[your-domain].com/client/oauth2/authorize for on-premise and https://[yourcompany].lime-crm.com/client/oauth2/authorize in cloud.

External Configuration¶

The external provider will 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 with the provider as well. This may be known as callback URL at most providers.

The scopes that we will request and which needs to be permitted by the provider include openid, email, and profile. These do not normally require any explicit configuration and are often implicitly enabled by default.

Lime CRM Configuration¶

On our end we need to specify the base URL which is the common URL for any user redirects and server-to-server requests. This pretty much always includes a unique application name or identifier and is often on a sub-path.

The provider parameter defines which external provider to use and will disable the external authentication entirely if it is missing or has a value that is not openid or azure.

Examples¶

During implementation we have evaluated and tested against a few external providers. Their example configurations are listed below.

Configuration for Auth0¶

config:
  authentication:
    provider: openid
    openid:
      base_url: 'https://<ChangeThis>.auth0.com' # Replace <ChangeThis> with your Auth0 domain
      access_token_path: '/token'
      authorize_path: '/authorize'
      client_id: <ChangeThis> # Replace <ChangeThis> with your Auth0 client ID
secrets:
  authentication:
    openid:
      client_secret: <ChangeThis>

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.

config:
  authentication:
    provider: openid
    openid:
      base_url: 'https://<ChangeThis>.okta.com/oauth2/v1/' # Replace <ChangeThis> with your Okta domain
      access_token_path: '/token'
      authorize_path: '/authorize'
      client_id: <ChangeThis> # Replace <ChangeThis> with your Okta client ID
secrets:
  authentication:
    openid:
      client_secret: <ChangeThis>

Common Pitfalls¶

Base URL¶

If the base URL is not properly configured the authentication flow might work for the redirects but fail when the user is redirected back to Lime CRM.

HTTP/HTTPS Misconfiguration¶

In testing the redirect URL will probably be on HTTP and either 127.0.0.1 or localhost, which will need to be updated in production. Always ensure that HTTPS is used in production environments to secure sensitive data and prevent man-in-the-middle attacks. If the base URL or redirect URL are configured with protocols they do not support 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.