External Authentication configuration

Authentication methods

Chamilo 2 supports a number of authentication methods, which have to be defined (given the high security requirements of this feature) inside the config/authentication.yaml file. This file can be updated in more recent versions of Chamilo through the template authentication.dist.yaml.

The authentication.yaml file uses the YAML syntax and parameters specific to each authentication method, so it might be a little tricky to configure. This page intends to reduce this difficulty by explaining all settings.

Each entry within the authentication block corresponds to an access URL (for example, default) and contains the enabled authentication methods, along with their requred parameters.

🧾 General structure

parameters:
  authentication:
    <access_url_id>:
      <auth_method>:
        <provider_name>:
          <config_key>: <value>
          <config_key>: <value>

• <access_url_id>: Access URL ID ( i.e. default, 2, 3).
• <auth_method>: Authentication method type (currently only oauth2).
• <provider_name>: Name of the specific provider (generic, facebook, keycloak, azure).
• <config_key> and <value>: Provider-specific configuration keys and values.

🛡️ Available authentication methods

All authentication methods include a force_as_login_method configuration key. When set to `true, this method becomes the exclusive authentication method for the user. Chamilo checks LDAP first, then enabled OAuth providers

🔗 oauth2.generic

Generic OAuth2 authentication compatible with any provider that implements the OAuth2 protocol (i.e., Google, GitLab).

Note: This is the equivalent of the OAuth2 plugin configuration from Chamilo v1.11.*.

Key	Type	Required	Description
enabled	boolean	Yes	Enables or disables this method
title	string	Yes	Display name for this method
client_id	string	Yes	OAuth2 client ID
client_secret	string	Yes	OAuth2 client secret
provider_options.urlAuthorize	Yes	string	The OAuth2 server URL to request authorization
provider_options.urlAccessToken	string	Yes	The OAuth2 server URL to request an access token
provider_options.urlResourceOwnerDetails	string	Yes	The OAuth2 server URL returning the identified user information as a JSON array
provider_options.responseResourceOwnerId	string	No	The array key to the user's OAuth2 identifier value (i.e. id). Default value: sub
provider_options.accessTokenMethod	string	No
provider_options.accessTokenResourceOwnerId	string	No
provider_options.scopeSeparator	string	No	Default value: ,
provider_options.responseError	string	No	Default value: error
provider_options.responseCode	string	No
provider_options.scopes	array	No
provider_options.pkceMethod	string	No
allow_create_new_users	boolean	No	Automatically creates new users if not found
allow_update_user_info	boolean	No	Updates user information from the provider
resource_owner_username_field	string	No	Key from the provider's user data to set the username
resource_owner_firstname_field	string	Yes	Key from the provider's user data to set the first name
resource_owner_lastname_field	string	Yes	Key from the provider's user data to set the last name
resource_owner_email_field	string	Yes	Key from the provider's user data to set the e-mail
resource_owner_status_field	string	No	The value for this key should be one of these integers: 1 (course manager / teacher), 3 (session administrator), 4 (DRH), 5 (student), 6 (anonymous)
resource_owner_teacher_status_field	string	No	If this value matches the value obtained from the resource_owner_status_field key, the user will have the role of Course Manager / Teacher
resource_owner_sessadmin_status_field	string	No	If this value matches the value obtained from the Response Resource Owner status key, the user will have the role of Session Administrator
resource_owner_hr_status_field	string	No	If this value matches the value obtained from the Response Resource Owner status key, the user will have the role of HRM
resource_owner_student_status_field	string	No	If this value matches the value obtained from the Response Resource Owner status key, the user will have the role of Student
resource_owner_anon_status_field	string	No	If this value matches the value obtained from the Response Resource Owner status key, the user will have the role of Anonymous
resource_owner_urls_field	string	No	The fetched values should be found in table access_url columns id or url. Example: data.0.domaines.*.url. * will be replaced by 0, then 1, then 2 and so on while it matches. There can be more than one * in this key expression. It means the URLs would be found at $jsonArray["data"]["domaines"][0]["url"] $jsonArray["data"]["domaines"][1]["url"] $jsonArray["data"]["domaines"][2]["url"]

🔵 oauth2.facebook

Enables login with Facebook. Requires a registered app at Meta for Developers.

Key	Type	Required	Description
enabled	boolean	Yes	Enables or disables this method
title	string	Yes	Display name for this method
client_id	string	Yes	Facebook App ID.
client_secret	string	Yes	Facebook App secret.
graph_api_version	string	No	Check current stable version here. Default value: v20.0

🧱 oauth2.keycloak

Authentication using a Keycloak server (OpenID Connect compatible).

Key	Type	Required	Description
enabled	boolean	Yes	Enables or disables this method
title	string	Yes	Display name for this method
client_id	string	Yes	Client ID registered in Keycloak
client_secret	string	Yes	Client secret
auth_server_url	string	Yes	Base URL of the Keycloak server
realm	string	Yes	Realm name
version	string	No	Keycloak version compatibility
encryptionAlgorithm	string	No	Encryption algorithm, i.e. RS256
encryptionKeyPath	string	No	Encryption key path, i.e. ../key.pem
encryptionKey	string	No	Encryption key, i.e. contents of key or certificate

☁️ oauth2.azure

Authentication via Microsoft Entra ID (Azure AD).

Key	Type	Required	Description
enabled	boolean	Yes	Enables or disables this method
title	string	Yes	Display name for this method
client_id	string	Yes	Azure client ID
client_secret	string	Yes	The shared client secret if you don't use a certificate
url_api	string	Yes	Microsoft Graph API base URL, i.e. https://graph.microsoft.com
tenant	string	No	Azure Tenant ID (required to run synchronization commands) Default value: common
force_logout	boolean	No	If true, shows a button to force logout session from Azure
provisioning	boolean	No	If true, automatically create new users (as students) from Azure when they are not in Chamilo
update_users	boolean	No	If true, allows user data to be updated at the start of the session
group_id.admin	string	No	The group ID can be found in the user group details (i.e. ae134eef-cbd4-4a32-ba99-49898a1314b6). If empty, no user will be automatically created as admin
group_id.session_admin	string	No	The group ID for session admins. If empty, no user will be automatically created as session admin
group_id.teacher	string	No	The group ID for teachers. If empty, no user will be automatically created as teacher
existing_user_verification_order	string	No	This value indicates the order in which the user will be searched in Chamilo to verify its existence. By default is 1, 2, 3. Where 1 is for the organisationemail extra field (Azure mail), 2 is for the azure_id extra field (Azure mailNickname), 3 is for the azure_uid extra field (Azure id)
deactivate_nonexisting_users	boolean	No	Compare registered users in Chamilo with those in Azure and deactivate accounts in Chamilo that do not exist in Azure
script_users_delta	boolean	No	Get newly created, updated, or deleted users without having to perform a full read of the entire user collection..
script_usergroups_delta	boolean	No	Get newly created, updated, or deleted groups, including group membership changes, without having to perform a full read of the entire group collection
group_filter_regex	string	No	Regular expression to filter groups (only matches will be synchronized), e.g. .*-FIL-.* .*-PAR-.* `.*(FIL
client_certificate_private_key	string	No	The contents of the client certificate private key, i.i. -----BEGIN RSA PRIVATE KEY-----\nMIIEog...G82ARGuI=\n-----END RSA PRIVATE KEY-----
client_certificate_thumbprint	string	No	The hexadecimal thumbprint of the client certificate, i.e. B4A94A83092455AC4D3AC827F02B61646EAAC43D
url_login	string	No	Domain to build login URL. Default value: https://login.microsoftonline.com/
path_authorize	string	No	Oauth path to authorize against
path_token	string	No	Oauth path to retrieve a token
scope	Array	No	Oauth scope send with the request
resource	string	No	Oauth resource field
auth_with_resource	string	No	Send resource field with auth-request
api_version	string	No	The API version to run against. Defaul value: 1.6
default_end_point_version	string	No	The endpoint version to run against. Default value: 1.0

🟦 ldap

Authentication that adheres to the LDAP protocol.

Key	Type	Required	Description
enabled	boolean	Yes	Enables or disables this method
title	string	Yes	Display name for this method
force_as_login_method	boolean	No	Forces LDAP to be the primary login method for the access URL
connection_string	string	Yes	LDAP connection URL (e.g., ldap://localhost:389 or ldaps://localhost:636)
protocol_version	int	Yes	LDAP protocol version. Defaul value: 3
referrals	boolean	No	Specifies whether to automatically follow referrals returned by the LDAP server
dn_string	string	No	DN template used to bind users directly (e.g., if the user have DN string in the form uid=jdoe,dc=chamilo,dc=org, then the dn_string will be uid={user_identifier},dc=chamilo,dc=org). Default value: {user_identifier}
query_string	string	No	Optional LDAP query template for searching users instead of direct bind
base_dn	string	No	Base DN from which LDAP searches will start
search_dn	string	No	DN used to bind for search operations (service account)
search_password	string	No	Password of the service account used for LDAP searches (e.g., CN=admin,dc=chamilo,dc=org)
filter	string	No	Optional additional LDAP filter (e.g., (objectClass=person))
uid_key	string	No	LDAP attribute used as the unique identifier (e.g., uid, sAMAccountName, etc.). Default value: uid
password_attribute	string	No	LDAP attribute where the user's password is stored (commonly userPassword)
data_correspondence.firstname	string	Yes	Mapping between Chamilo user's firstname and LDAP attribute
data_correspondence.lastname	string	Yes	Mapping between Chamilo user's lastname and LDAP attribute
data_correspondence.email	string	Yes	Mapping between Chamilo user's email and LDAP attribute
data_correspondence.locale	string	No	Mapping between Chamilo user's locale and LDAP attribute
data_correspondence.role	string	No	Mapping between Chamilo user's role and LDAP attribute
data_correspondence.phone	string	No	Mapping between Chamilo user's phone and LDAP attribute
data_correspondence.active	string	No	Mapping between Chamilo user's active and LDAP attribute
data_correspondence.admin	string	No	Mapping between Chamilo user's admin and LDAP attribute