External Authentication configuration

External Authentication Configuration

Chamilo 2 supports multiple external authentication methods configured through the config/authentication.yaml file. A template file authentication.dist.yaml is provided as a starting point in recent versions.

This file uses YAML syntax. Each entry within the authentication block corresponds to an access URL and contains the enabled authentication methods along with their required parameters.

Table of contents

• General structure
• Authentication priority
• OAuth2 - Generic
• OAuth2 - Facebook
• OAuth2 - Keycloak
• OAuth2 - Azure (Microsoft Entra ID)
• LDAP
• SCIM (User provisioning)

---

General structure

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

Placeholder	Description	Examples
<access_url_id>	Access URL ID	default, 2, 3
<auth_method>	Authentication method type	oauth2, ldap, scim
<provider_name>	Provider name (OAuth2 only)	generic, facebook, keycloak, azure
<config_key>	Provider-specific configuration key	See each method below

Authentication priority

When multiple methods are enabled, Chamilo checks them in the following order:

1. LDAP (if enabled and force_as_login_method is true)
2. OAuth2 providers (in the order they appear in the configuration)

All authentication methods support the force_as_login_method key. When set to true, that method becomes the exclusive authentication method for the access URL.

---

OAuth2: Generic

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

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

Basic settings

Key	Type	Required	Description
enabled	boolean	Yes	Enables or disables this method
title	string	Yes	Display name shown on the login page
client_id	string	Yes	OAuth2 client ID
client_secret	string	Yes	OAuth2 client secret
allow_create_new_users	boolean	No	Automatically creates new users if not found in Chamilo
allow_update_user_info	boolean	No	Updates user information from the provider on each login

Provider options

These keys are nested under provider_options.

Key	Type	Required	Description
urlAuthorize	string	Yes	URL to request authorization
urlAccessToken	string	Yes	URL to request an access token
urlResourceOwnerDetails	string	Yes	URL returning the authenticated user's information as JSON
responseResourceOwnerId	string	No	JSON key for the user's unique identifier. Default: sub
accessTokenMethod	string	No	HTTP method for the access token request
accessTokenResourceOwnerId	string	No	Key for the resource owner ID in the access token response
scopeSeparator	string	No	Character used to separate scopes. Default: ,
responseError	string	No	JSON key for error messages. Default: error
responseCode	string	No	JSON key for error codes
scopes	array	No	OAuth2 scopes to request. Default: ['openid']
pkceMethod	string	No	PKCE method (e.g., S256)

User field mapping

These keys map the provider's JSON response fields to Chamilo user attributes.

Key	Type	Required	Description
resource_owner_username_field	string	No	Field to use as username
resource_owner_firstname_field	string	Yes	Field to use as first name
resource_owner_lastname_field	string	Yes	Field to use as last name
resource_owner_email_field	string	Yes	Field to use as e-mail

Role mapping

These keys control how the provider's response determines the user's role in Chamilo.

Key	Type	Required	Description
resource_owner_status_field	string	No	JSON key containing the user's role identifier
resource_owner_teacher_status_field	string	No	Value that maps to Course Manager / Teacher (role 1)
resource_owner_sessadmin_status_field	string	No	Value that maps to Session Administrator (role 3)
resource_owner_hr_status_field	string	No	Value that maps to HRM (role 4)
resource_owner_student_status_field	string	No	Value that maps to Student (role 5)
resource_owner_anon_status_field	string	No	Value that maps to Anonymous (role 6)

Access URL mapping

Key	Type	Required	Description
resource_owner_urls_field	string	No	JSON path expression to extract access URLs. Values should match access_url.id or access_url.url in Chamilo.

The * wildcard iterates over array indices. For example, data.0.domaines.*.url resolves to:

$jsonArray["data"][0]["domaines"][0]["url"]
$jsonArray["data"][0]["domaines"][1]["url"]
$jsonArray["data"][0]["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 shown on the login page
client_id	string	Yes	Facebook App ID
client_secret	string	Yes	Facebook App secret
graph_api_version	string	No	Graph API version. See available versions. Default: 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 shown on the login page
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 (e.g., RS256)
encryptionKeyPath	string	No	Path to the encryption key file (e.g., ../key.pem)
encryptionKey	string	No	Encryption key or certificate contents

---

OAuth2: Azure

Authentication via Microsoft Entra ID (formerly Azure AD).

Connection settings

Key	Type	Required	Description
enabled	boolean	Yes	Enables or disables this method
title	string	Yes	Display name shown on the login page
client_id	string	Yes	Azure application (client) ID
client_secret	string	Yes	Shared client secret (not needed if using a certificate)
url_api	string	Yes	Microsoft Graph API base URL (e.g., https://graph.microsoft.com)
tenant	string	No	Azure Tenant ID. Required for synchronization commands. Default: common
url_login	string	No	Login domain. Default: https://login.microsoftonline.com/
path_authorize	string	No	OAuth authorization path
path_token	string	No	OAuth token path
scope	array	No	OAuth scopes sent with the request
resource	string	No	OAuth resource field
auth_with_resource	string	No	Send the resource field with the auth request
api_version	string	No	API version. Default: 1.6
default_end_point_version	string	No	Endpoint version. Default: 1.0

Certificate authentication

Use these instead of client_secret to authenticate with a client certificate.

Key	Type	Required	Description
client_certificate_private_key	string	No	Contents of the private key (PEM format)
client_certificate_thumbprint	string	No	Hexadecimal thumbprint of the certificate (e.g., B4A94A83092455AC4D3AC827F02B61646EAAC43D)

User provisioning and synchronization

Key	Type	Required	Description
provisioning	boolean	No	Automatically create new users (as students) from Azure when not found in Chamilo
update_users	boolean	No	Update user data from Azure at the start of each session
force_logout	boolean	No	Show a button to force logout from the Azure session
deactivate_nonexisting_users	boolean	No	Deactivate Chamilo accounts that no longer exist in Azure
script_users_delta	boolean	No	Sync only newly created, updated, or deleted users (delta sync instead of full read)
script_usergroups_delta	boolean	No	Sync only changed groups and memberships (delta sync instead of full read)

Group-based role mapping

Key	Type	Required	Description
group_id.admin	string	No	Azure group ID for platform administrators
group_id.session_admin	string	No	Azure group ID for session administrators
group_id.teacher	string	No	Azure group ID for teachers
group_filter_regex	string	No	Regex to filter which groups are synchronized (e.g., .*(FIL|PAR).*)

User verification

Key	Type	Required	Description
existing_user_verification_order	string	No	Order for matching Azure users to Chamilo accounts. Default: 1, 2, 3

The verification order values are:

Order	Chamilo extra field	Azure attribute
1	organisationemail	mail
2	azure_id	mailNickname
3	azure_uid	id

---

LDAP

Authentication using the LDAP protocol (compatible with Active Directory, OpenLDAP, etc.).

Connection settings

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 as the exclusive login method for this access URL
connection_string	string	Yes	LDAP server URL (e.g., ldap://localhost:389 or ldaps://localhost:636)
protocol_version	int	Yes	LDAP protocol version. Default: 3
referrals	boolean	No	Automatically follow referrals returned by the LDAP server

Bind and search settings

Key	Type	Required	Description
dn_string	string	No	DN template for direct user bind (e.g., uid={user_identifier},dc=chamilo,dc=org). Default: {user_identifier}
query_string	string	No	LDAP query template for searching users (alternative to direct bind)
base_dn	string	No	Base DN from which searches start
search_dn	string	No	Service account DN used for search operations
search_password	string	No	Service account password (e.g., CN=admin,dc=chamilo,dc=org)
filter	string	No	Additional LDAP filter (e.g., (objectClass=person))
uid_key	string	No	Attribute used as the unique identifier (e.g., uid, sAMAccountName). Default: uid
password_attribute	string	No	Attribute storing the user's password (e.g., userPassword)

User attribute mapping

Key	Type	Required	Description
data_correspondence.firstname	string	Yes	LDAP attribute for the user's first name
data_correspondence.lastname	string	Yes	LDAP attribute for the user's last name
data_correspondence.email	string	Yes	LDAP attribute for the user's email
data_correspondence.locale	string	No	LDAP attribute for the user's locale
data_correspondence.role	string	No	LDAP attribute for the user's role
data_correspondence.phone	string	No	LDAP attribute for the user's phone
data_correspondence.active	string	No	LDAP attribute for the user's active status
data_correspondence.admin	string	No	LDAP attribute for the user's admin status

---

SCIM (User provisioning)

SCIM (System for Cross-domain Identity Management) is used for automated user provisioning and synchronization from external identity providers.

SCIM is not an interactive login method. It creates, updates, and deactivates users programmatically.

Configuration

Key	Type	Required	Description
enabled	boolean	Yes	Enables or disables SCIM provisioning
auth_source	string	No	Authentication source for managed users. Default: platform

Authentication

SCIM requests are authenticated using a static token defined in the .env file:

SCIM_TOKEN=your-secure-random-token

API Endpoints (SCIM v2)

Resource Types

Method	Endpoint
GET	/scim/v2/ResourceTypes
GET	/scim/v2/ResourceTypes/{resourceType}

Schemas

Method	Endpoint
GET	/scim/v2/Schemas
GET	/scim/v2/Schemas/{schemaId}

Users

Method	Endpoint	Description
GET	/scim/v2/Users	List all users
POST	/scim/v2/Users	Create a user
GET	/scim/v2/Users/{uuid}	Get a specific user
PUT	/scim/v2/Users/{uuid}	Replace a user
PATCH	/scim/v2/Users/{uuid}	Update a user
DELETE	/scim/v2/Users/{uuid}	Delete a user