User directory

Overview

The central user directory allows users to use the same username and password across apps.

The system acts as an OpenID Connect (OIDC) provider as well as an LDAP server.

When packaging apps, OIDC integration is preferred over LDAP. The main advantages the OIDC integration offers over LDAP are:

• True single sign-on across apps. Once logged into the main dashboard, users can automatically login to apps.
• Manage app sessions from the Dashboard
• 2FA support across apps
• More secure since apps never see the user's password

Lock profile

User profiles can be locked to prevent users from changing their email and full name. Configure this setting in Users -> Settings.

Mandatory 2FA

Require all users to set up two-factor authentication by enabling Mandatory 2FA in Users -> Settings.

When enabled, all existing users without a 2FA setup are logged out immediately.

When users without 2FA attempt to log in, they must set up 2FA:

OpenID connect

OpenID Connect 1.0 is a simple identity layer on top of the OAuth 2.0 protocol.

The system can act as an OpenID Connect (OIDC) provider. Apps hosted on the same server integrate using the oidc addon.

External apps have to configured with OpenID Client credentials.

The OIDC server provides the following scopes and corresponding claims:

Scope	Claim
profile	family_name, given_name, locale (always en-US), name, preferred_username
email	email, email_verified

The sub property (the unique user identifier) is the username.

OIDC Provider Name

The OIDC Provider Name is the same as the Name. Supporting apps will pick up this value and show this in the Login Button text.

OIDC client

OIDC client credentials can be created in Users -> OpenID.

The system generates the Client ID and Client secret for configuring your OIDC client.

Configure the provider in the client app:

For most clients, add openid (mandatory), profile, and email scopes (space-separated). This ensures the app has access to user profile claims.

Endpoints

Name	URL
Discovery URL	https://my.cloudron.example/.well-known/openid-configuration and https://my.cloudron.example/openid/.well-known/openid-configuration
Issuer URL	https://my.cloudron.example/openid
Auth URL	https://my.cloudron.example/openid/auth
Token URL	https://my.cloudron.example/openid/token
Keys URL (Certificate URL)	https://my.cloudron.example/openid/jwks and https://my.cloudron.example/openid/jwks_rsaonly
Profile URL	https://my.cloudron.example/openid/me

Cloudflare Access

Cloudflare Access has a bug with the OKP key type. Use the RSA-only jwks_rsaonly URL as a workaround.

LDAP server

The system can act as a read-only LDAP server.

Apps hosted on the same server integrate automatically using the ldap addon and no further configuration is required.

External apps can list users and authenticate with the LDAP Server. LDAP Server can be enabled from Users -> LDAP:

For security reasons, the LDAP server only accepts connections from whitelisted IPs and ranges.

LDAP client

Configure external apps to use the Directory Server:

• Use the dashboard domain as the LDAP server hostname. Port 636 (TLS). LDAP server uses the same certificate as the dashboard domain.
• Set cn=admin,ou=system,dc=cloudron as the Bind DN. Use the secret listed in the above screenshot as the Bind Password.

Users:

• Users DN is ou=users,dc=cloudron.
• Use user as objectclass
• Username attribute is uid
• RDN attribute is cn
• UUID attribute is uid
• User LDAP filter is (&(objectclass=user)(|(username=%uid)(mail=%uid))) . Note that you will have to adjust the syntax based on the app. The objectclass might be redundant. %uid is a template variable for the username the user enters in the app's login form.

Groups:

• Groups DN is ou=groups,dc=cloudron.
• Use group as objectclass for groups
• Groupname attribute is cn
• Group LDAP filter is (&(objectclass=group)(cn=%gname)). Adjust the syntax based on the app. %gname is the group name you are searching for.

Troubleshooting

Test the setup as follows:

$ ldapsearch  -x -b "ou=users,dc=cloudron" -D "cn=admin,ou=system,dc=cloudron" -W -H ldaps://my.example.com:636
Enter LDAP Password:
# Extended LDIF
#
# Ldapv3
# base <ou=users,dc=cloudron> with scope subtree
# Filter: (objectclass=*)
# Requesting: ALL
#

# Uid-0cfbd3d8-6547-4332-9415-dadfe8b78ac4, users, Cloudron
dn: cn=uid-0cfbd3d8-6547-4332-9415-dadfe8b78ac4,ou=users,dc=cloudron
objectclass: user
objectclass: inetorgperson
objectclass: person
objectcategory: person
...

External directory connector

The External Directory connector allows users from an existing LDAP or Active Directory (AD) to authenticate.

When enabled, profile information (Username, Display Name, Email) is used from LDAP/AD.

2FA behavior depends on the provider. The Cloudron provider uses the external directory's 2FA. Other providers allow users to set up 2FA locally.

The user's role and active state are local and not synced from LDAP.

Providers

Cloudron

To use another Cloudron as the external LDAP directory, do the following:

• Enable LDAP Server in the Users => LDAP menu. Whitelist the server and specify a secure secret.

• On the server using the external directory, go to Users => LDAP => Connect an External Directory and select Cloudron as the provider.

2FA Support

The Cloudron connector is the only one that supports 2FA. If a user has 2FA enabled in the LDAP Server, 2FA is required to log in. The Mandatory 2FA check is skipped for external users. Enable it on the other server to enforce 2FA.

JumpCloud

Configuration options for JumpCloud external LDAP directory:

• Server URL: ldaps://ldap.jumpcloud.com:636
• Base DN: ou=users,o=3214565,dc=jumpcloud,dc=com
• Filter: (objectClass=inetorgperson)
• Username field: uid
• Group Base DN: ou=Users,o=5d55499ce559751c02a1bcd1,dc=jumpcloud,dc=com
• Group Filter: (obiectClass=arounOfNames)
• Groupname Field: cn
• Bind DN/Username (optional): uid=ldap_admin,ou=Users,o=3214565,dc=jumpcloud,dc=com
• Bind password: admin password

Okta

To use Okta integration:

• Enable the LDAP interface in Okta from the Directory Integrations page.

• Okta uses email as the default UID, but usernames are required for LDAP integration. If a username field exists in Okta, use it as the username field. Otherwise, create a new field in the profile editor.

• Configuration (replace 'org' below):

  • Server URL: ldaps://<org>.ldap.okta.com
  • Base DN: ou=users, dc=<org>, dc=okta, dc=com
  • Filter: (objectClass=inetorgperson)
  • Bind DN: uid=<admin>, dc=<org>, dc=okta, dc=com
  • Bind password: admin password
  • Username field: see above

Disable

Disables External LDAP authentication. When disabled, all existing users are switched to local.

Sync

The local directory is synced with the external directory every 4 hours.

Use the Sync button to trigger a manual sync. Check the logs for any conflicts.

External users and groups are indicated in the User/Group edit view:

Users are not deleted

Users removed from the external directory are not deleted during sync. This is not a security issue because the user can no longer authenticate.

Auto-create users

Use the Automatically create users when they login to Cloudron option to automatically create users locally on first login.

When disabled, users are only created during Sync.

Sync groups

When enabled, external groups are created locally with their user associations.

External groups are read-only. Local users cannot be added to them.

Local groups can contain both local and external users.

Groups are not deleted

Groups removed from the external directory are not deleted during sync.

Self signed certificate

Use the Accept Self-signed certificate option to accept any self-signed certificate from the LDAP server.