How to add Magento 2 system configuration fields
Magento 2 allows developers to add custom system configuration fields so that store administrators can manage module behaviour directly from the backend. These values are stored in the core_config_data table, similar to Magento 1.
This guide explains how to create system configuration fields using
system.xml and secure them with proper ACL permissions.
Who Is This Useful For?
This approach is especially useful for developers who:
- Are building a Magento 2 custom module
- Need configurable values in the Admin panel
- Want scope-based settings (default / website / store view)
Example Scenario
In this example, we create an Importer module that connects to an external FTP server. The following configuration fields are required:
- Server – FTP server IP or domain name
- User – FTP username
- Password – Secure password field
- Path – Directory containing import files
All values are simple text fields except the password, which uses Magento’s encrypted password field type.
Step 1: Define ACL Permissions (acl.xml)
Magento requires ACL rules to control who can access or modify system
configuration values. Create an acl.xml file under
etc directory of your module.
<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="urn:magento:framework:Acl/etc/acl.xsd">
<acl>
<resources>
<resource id="Magento_Backend::admin">
<resource id="Magento_Backend::stores">
<resource id="Magento_Backend::stores_settings">
<resource id="Magento_Config::config">
<resource id="Example_Importer::config"
title="Importer"
sortOrder="50" />
</resource>
</resource>
</resource>
</resource>
</resources>
</acl>
</config>
Replace Example_Importer with your module name using the
format Vendor_Module. This resource will appear under
System → User Roles.
Step 2: Create System Configuration (system.xml)
Next, create a system.xml file under:
etc/adminhtml/system.xml
This file defines tabs, sections, groups, and fields shown in the Admin configuration panel.
<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Config:etc/system_file.xsd">
<system>
<tab id="example_tab" translate="label" sortOrder="1000">
<label>Example</label>
</tab>
<section id="example_section" translate="label" sortOrder="100"
showInDefault="1" showInWebsite="1" showInStore="1">
<label>Importer</label>
<tab>example_tab</tab>
<resource>Example_Importer::config</resource>
<group id="general" translate="label" sortOrder="10"
showInDefault="1" showInWebsite="1" showInStore="1">
<label>General</label>
<field id="ftp_server" type="text" sortOrder="10"
showInDefault="1" showInWebsite="1" showInStore="1">
<label>Server</label>
</field>
<field id="ftp_user" type="text" sortOrder="20"
showInDefault="1" showInWebsite="1" showInStore="1">
<label>User</label>
</field>
<field id="ftp_password" type="password" sortOrder="30"
showInDefault="1" showInWebsite="1" showInStore="1">
<label>Password</label>
</field>
<field id="ftp_dir" type="text" sortOrder="40"
showInDefault="1" showInWebsite="1" showInStore="1">
<label>Directory</label>
</field>
</group>
</section>
</system>
</config>
It is recommended to create a dedicated vendor tab and group similar modules under it to keep the Admin panel clean.
Field Attributes Explained
- id – Configuration key used to fetch value in code
- type – Input type (text, password, select, etc.)
- showInDefault – Global scope configuration
- showInWebsite – Website-level override
- showInStore – Store-view-level override
Conclusion
Adding system configuration fields in Magento 2 is a structured and powerful way to make your modules flexible and admin-friendly. By defining ACL permissions, configuration tabs, and properly scoped fields, you ensure security, scalability, and clean backend management.
These values can later be retrieved programmatically and used across models, helpers, services, and cron jobs.