Skip to content
  • About
    • What is Symfony?
    • Community
    • News
    • Contributing
    • Support
  • Documentation
    • Symfony Docs
    • Symfony Book
    • Screencasts
    • Symfony Bundles
    • Symfony Cloud
    • Training
  • Services
    • SensioLabs Professional services to help you with Symfony
    • Platform.sh for Symfony Best platform to deploy Symfony apps
    • SymfonyInsight Automatic quality checks for your apps
    • Symfony Certification Prove your knowledge and boost your career
    • Blackfire Profile and monitor performance of your apps
  • Other
  • Blog
  • Download
sponsored by SensioLabs
  1. Home
  2. Documentation
  3. Security
  4. Built-in Authentication Providers
  • Documentation
  • Book
  • Reference
  • Bundles
  • Cloud

Table of Contents

  • HTTP Basic Authentication
  • X.509 Client Certificate Authentication
  • REMOTE_USER Based Authentication

Built-in Authentication Providers

Edit this page

Warning: You are browsing the documentation for Symfony 5.1, which is no longer maintained.

Read the updated version of this page for Symfony 6.2 (the current stable version).

Built-in Authentication Providers

If you need to add authentication to your app, we recommend using Guard authentication because it gives you full control over the process.

But, Symfony also offers a number of built-in authentication providers: systems that are easier to implement, but harder to customize. If your authentication use-case matches one of these exactly, they're a great option:

  • form_login
  • http_basic
  • LDAP via HTTP Basic or Form Login
  • json_login
  • X.509 Client Certificate Authentication (x509)
  • REMOTE_USER Based Authentication (remote_user)

HTTP Basic Authentication

HTTP Basic authentication asks credentials (username and password) using a dialog in the browser. The credentials are sent without any hashing or encryption, so it's recommended to use it with HTTPS.

To support HTTP Basic authentication, add the http_basic key to your firewall:

  • YAML
  • XML
  • PHP
1
2
3
4
5
6
7
8
9
# config/packages/security.yaml
security:
    # ...

    firewalls:
        main:
            # ...
            http_basic:
                realm: Secured Area
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
<!-- config/packages/security.xml -->
<?xml version="1.0" encoding="UTF-8"?>
<srv:container xmlns="http://symfony.com/schema/dic/security"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:srv="http://symfony.com/schema/dic/services"
    xsi:schemaLocation="http://symfony.com/schema/dic/services
        https://symfony.com/schema/dic/services/services-1.0.xsd
        http://symfony.com/schema/dic/security
        https://symfony.com/schema/dic/security/security-1.0.xsd">

    <config>
        <!-- ... -->

        <firewall name="main">
            <http-basic realm="Secured Area"/>
        </firewall>
    </config>
</srv:container>
1
2
3
4
5
6
7
8
9
10
11
12
// config/packages/security.php
$container->loadFromExtension('security', [
    // ...

    'firewalls' => [
        'main' => [
            'http_basic' => [
                'realm' => 'Secured Area',
            ],
        ],
    ],
]);

That's it! Symfony will now be listening for any HTTP basic authentication data. To load user information, it will use your configured user provider.

Note: you cannot use the log out with http_basic. Even if you log out, your browser "remembers" your credentials and will send them on every request.

X.509 Client Certificate Authentication

When using client certificates, your web server is doing all the authentication process itself. With Apache, for example, you would use the SSLVerifyClient Require directive.

Enable the x509 authentication for a particular firewall in the security configuration:

  • YAML
  • XML
  • PHP
1
2
3
4
5
6
7
8
9
# config/packages/security.yaml
security:
    # ...

    firewalls:
        main:
            # ...
            x509:
                provider: your_user_provider
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
<!-- config/packages/security.xml -->
<?xml version="1.0" encoding="UTF-8"?>
<srv:container xmlns="http://symfony.com/schema/dic/security"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:srv="http://symfony.com/schema/dic/services"
    xsi:schemaLocation="http://symfony.com/schema/dic/services
        https://symfony.com/schema/dic/services/services-1.0.xsd
        http://symfony.com/schema/dic/security
        https://symfony.com/schema/dic/security/security-1.0.xsd">

    <config>
        <!-- ... -->

        <firewall name="main">
            <!-- ... -->
            <x509 provider="your_user_provider"/>
        </firewall>
    </config>
</srv:container>
1
2
3
4
5
6
7
8
9
10
11
12
13
// config/packages/security.php
$container->loadFromExtension('security', [
    // ...

    'firewalls' => [
        'main' => [
            // ...
            'x509' => [
                'provider' => 'your_user_provider',
            ],
        ],
    ],
]);

By default, the firewall provides the SSL_CLIENT_S_DN_Email variable to the user provider, and sets the SSL_CLIENT_S_DN as credentials in the PreAuthenticatedToken. You can override these by setting the user and the credentials keys in the x509 firewall configuration respectively.

Note

An authentication provider will only inform the user provider of the username that made the request. You will need to create (or use) a "user provider" that is referenced by the provider configuration parameter (your_user_provider in the configuration example). This provider will turn the username into a User object of your choice. For more information on creating or configuring a user provider, see:

  • Security User Providers

REMOTE_USER Based Authentication

A lot of authentication modules, like auth_kerb for Apache, provide the username using the REMOTE_USER environment variable. This variable can be trusted by the application since the authentication happened before the request reached it.

To configure Symfony using the REMOTE_USER environment variable, enable the corresponding firewall in your security configuration:

  • YAML
  • XML
  • PHP
1
2
3
4
5
6
7
# config/packages/security.yaml
security:
    firewalls:
        main:
            # ...
            remote_user:
                provider: your_user_provider
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
<!-- config/packages/security.xml -->
<?xml version="1.0" ?>
<srv:container xmlns="http://symfony.com/schema/dic/security"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:srv="http://symfony.com/schema/dic/services"
    xsi:schemaLocation="http://symfony.com/schema/dic/services
        https://symfony.com/schema/dic/services/services-1.0.xsd
        http://symfony.com/schema/dic/security
        https://symfony.com/schema/dic/security/security-1.0.xsd">

    <config>
        <firewall name="main">
            <remote-user provider="your_user_provider"/>
        </firewall>
    </config>
</srv:container>
1
2
3
4
5
6
7
8
9
10
// config/packages/security.php
$container->loadFromExtension('security', [
    'firewalls' => [
        'main' => [
            'remote_user' => [
                'provider' => 'your_user_provider',
            ],
        ],
    ],
]);

The firewall will then provide the REMOTE_USER environment variable to your user provider. You can change the variable name used by setting the user key in the remote_user firewall configuration.

Note

Just like for X509 authentication, you will need to configure a "user provider". See the previous note for more information.

This work, including the code samples, is licensed under a Creative Commons BY-SA 3.0 license.
TOC
    Version
    We stand with Ukraine.
    Version:
    Be safe against critical risks to your projects and businesses

    Be safe against critical risks to your projects and businesses

    Check Code Performance in Dev, Test, Staging & Production

    Check Code Performance in Dev, Test, Staging & Production

    Symfony footer

    ↓ Our footer now uses the colors of the Ukrainian flag because Symfony stands with the people of Ukraine.

    Avatar of Cosmic Mac, a Symfony contributor

    Thanks Cosmic Mac for being a Symfony contributor

    1 commit • 2 lines changed

    View all contributors that help us make Symfony

    Become a Symfony contributor

    Be an active part of the community and contribute ideas, code and bug fixes. Both experts and newcomers are welcome.

    Learn how to contribute

    Symfony™ is a trademark of Symfony SAS. All rights reserved.

    • What is Symfony?

      • Symfony at a Glance
      • Symfony Components
      • Case Studies
      • Symfony Releases
      • Security Policy
      • Logo & Screenshots
      • Trademark & Licenses
      • symfony1 Legacy
    • Learn Symfony

      • Symfony Docs
      • Symfony Book
      • Reference
      • Bundles
      • Best Practices
      • Training
      • eLearning Platform
      • Certification
    • Screencasts

      • Learn Symfony
      • Learn PHP
      • Learn JavaScript
      • Learn Drupal
      • Learn RESTful APIs
    • Community

      • SymfonyConnect
      • Support
      • How to be Involved
      • Code of Conduct
      • Events & Meetups
      • Projects using Symfony
      • Downloads Stats
      • Contributors
      • Backers
    • Blog

      • Events & Meetups
      • A week of symfony
      • Case studies
      • Cloud
      • Community
      • Conferences
      • Diversity
      • Documentation
      • Living on the edge
      • Releases
      • Security Advisories
      • SymfonyInsight
      • Twig
      • SensioLabs
    • Services

      • SensioLabs services
      • Train developers
      • Manage your project quality
      • Improve your project performance
      • Host Symfony projects

      Deployed on

    Follow Symfony

    Search by Algolia