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 and 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 should work with others.
• Users that whish to login 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 be automatically logged in as the user with a matching email address as their username in the Lime database.

External Configuration

The external provider will validate that an an authorization token is created for a trusted endpoint and verify that the user is not redirected somewhere they should not be. For this reason the redirect URL configured in our config 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 evaluted and tested against a few external providers. Their example configurations are listed below.

Configuration for Auth0

config:
  authentication:
    provider: openid
    openid:
      redirect_url: 'https://<ChangeThis>/client/oauth2/authorize'
      base_url: 'https://<ChangeThis>.auth0.com'
      access_token_path: '/token'
      authorize_path: '/authorize'
      client_id: <ChangeThis>
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:
      redirect_url: 'https://<ChangeThis>/client/oauth2/authorize'
      base_url: 'https://<ChangeThis>.okta.com/oauth2/v1/'
      access_token_path: '/token'
      authorize_path: '/authorize'
      client_id: <ChangeThis>
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.

Callback URL / Redirect URL

If this is not configured properly the external provider will refuse to redirect the user back to Lime CRM. If the redirect URL is misconfigured the user will end up somewhere else and not be authenticated properly.

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. If the base URL or redirect URL are configured on 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 or the user will not be able to log in.