Where Are Passwords Stored In Symfony For Services

Security

Edit this page

The User
- Loading the User: The User Provider
- Registering the User: Hashing Passwords
The Firewall
Authenticating Users
- Class Login
- JSON Login
- HTTP Basic
- Login Link
- X.509 Customer Certificates
- Remote Users
- Limiting Login Attempts
Logging Out
- Customizing Logout
Fetching the User Object
- Fetching the User from a Service
- Fetch the User in a Template
Admission Control (Say-so)
- Roles
- Add Code to Deny Admission
- Assuasive Unsecured Access (i.e. Anonymous Users)
- Granting Anonymous Users Admission in a Custom Voter
- Setting Individual User Permissions
- Checking to encounter if a User is Logged In (IS_AUTHENTICATED_FULLY)
Understanding how Users are Refreshed from the Session
- Comparing Users Manually with EquatableInterface
Security Events
- Authentication Events
- Other Events
Often Asked Questions
Learn More than
- Hallmark (Identifying/Logging in the User)
- Authorization (Denying Access)

Security

Symfony provides many tools to secure your application. Some HTTP-related security tools, like secure session cookies and CSRF protection are provided by default. The SecurityBundle, which you will larn virtually in this guide, provides all hallmark and authorisation features needed to secure your application.

To get started, install the SecurityBundle:

If you have Symfony Flex installed, this also creates a security.yaml configuration file for you:

That'south a lot of config! In the adjacent sections, the three master elements are discussed:

The User (providers): Whatsoever secured section of your application needs some concept of a user. The user provider loads users from any storage (e.g. the database) based on a "user identifier" (e.grand. the user's email address);
The Firewall & Authenticating Users (firewalls): The firewall is the core of securing your application. Every request inside the firewall is checked if information technology needs an authenticated user. The firewall also takes care of authenticating this user (e.yard. using a login form);
Admission Control (Potency) (access_control): Using access control and the say-so checker, you control the required permissions to perform a specific activeness or visit a specific URL.

The User

Permissions in Symfony are always linked to a user object. If yous need to secure (parts of) your awarding, yous need to create a user form. This is a class that implements UserInterface. This is often a Doctrine entity, but y'all tin can also utilize a dedicated Security user grade.

The easiest mode to generate a user form is using the make:user command from the MakerBundle:

If your user is a Doctrine entity, like in the example above, don't forget to create the tables past creating and running a migration:

Loading the User: The User Provider

Also creating the entity, the brand:user command likewise adds config for a user provider in your security configuration:

YAML
XML
PHP

This user provider knows how to (re)load users from a storage (east.g. a database) based on a "user identifier" (due east.g. the user's email address or username). The configuration above uses Doctrine to load the User entity using the e-mail property as "user identifier".

User providers are used in a couple places during the security lifecycle:

Load the User based on an identifier: During login (or any other authenticator), the provider loads the user based on the user identifier. Some other features, similar user impersonation and Remember Me also use this.
Reload the User from the session: At the beginning of each request, the user is loaded from the session (unless your firewall is stateless). The provider "refreshes" the user (e.g. the database is queried again for fresh data) to brand sure all user data is up to appointment (and if necessary, the user is de-authenticated/logged out if something changed). Encounter Security for more information about this process.

Symfony comes with several built-in user providers:

Entity User Provider: Loads users from a database using Doctrine;
LDAP User Provider: Loads users from a LDAP server;
Memory User Provider: Loads users from a configuration file;
Chain User Provider: Merges two or more than user providers into a new user provider.

The built-in user providers cover the almost common needs for applications, but y'all can too create your own custom user provider.

Note

Sometimes, you lot demand to inject the user provider in another class (e.g. in your custom authenticator). All user providers follow this pattern for their service ID: security.user.provider.concrete.<your-provider-name> (where <your-provider-name> is the configuration key, e.g. app_user_provider). If yous only have ane user provider, y'all can autowire it using the UserProviderInterface type-hint.

Registering the User: Hashing Passwords

Many applications require a user to log in with a password. For these applications, the SecurityBundle provides password hashing and verification functionality.

Outset, brand sure your User course implements the PasswordAuthenticatedUserInterface:

Then, configure which password hasher should be used for this class. If your security.yaml file wasn't already pre-configured, and then make:user should have done this for you:

YAML
XML
PHP

Now that Symfony knows how yous want to hash the passwords, you tin use the UserPasswordHasherInterface service to practice this before saving your users to the database:

Tip

The make:registration-class maker command tin can assistance you set-upwardly the registration controller and add features like email address verification using the SymfonyCastsVerifyEmailBundle.

You tin can as well manually hash a countersign by running:

Read more about all available hashers and password migration in Countersign Hashing and Verification.

The Firewall

The firewalls department of config/packages/security.yaml is the about important section. A "firewall" is your authentication organization: the firewall defines which parts of your awarding are secured and how your users will be able to authenticate (e.g. login form, API token, etc).

YAML
XML
PHP

Only one firewall is active on each request: Symfony uses the pattern key to find the get-go match (you can also match by host or other things).

The dev firewall is really a imitation firewall: it makes sure that you don't accidentally block Symfony'southward dev tools - which live under URLs like /_profiler and /_wdt.

All real URLs are handled past the primary firewall (no blueprint key means it matches all URLs). A firewall can have many modes of authentication, in other words, it enables many ways to ask the question "Who are you?".

Frequently, the user is unknown (i.e. non logged in) when they kickoff visit your website. If you visit your homepage correct at present, you will have access and you lot'll see that you lot're visiting a page behind the firewall in the toolbar:

Visiting a URL under a firewall doesn't necessarily require you to be authenticated (eastward.grand. the login grade has to be accessible or some parts of your application are public). You'll learn how to restrict access to URLs, controllers or annihilation else within your firewall in the access control section.

Tip

The lazy anonymous mode prevents the session from existence started if there is no need for authorization (i.east. explicit check for a user privilege). This is important to proceed requests cacheable (meet HTTP Cache).

Note

If you practice not meet the toolbar, install the profiler with:

Now that we sympathise our firewall, the side by side pace is to create a manner for your users to authenticate!

Authenticating Users

During authentication, the system tries to find a matching user for the visitor of the webpage. Traditionally, this was done using a login form or a HTTP basic dialog in the browser. However, the SecurityBundle comes with many other authenticators:

Form Login
JSON Login
HTTP Basic
Login Link
10.509 Client Certificates
Remote users
Custom Authenticators

Tip

If your application logs users in via a third-political party service such every bit Google, Facebook or Twitter (social login), check out the HWIOAuthBundle customs bundle.

About websites have a login form where users authenticate using an identifier (e.g. e-mail address or username) and a countersign. This functionality is provided by the grade login authenticator.

Kickoff, create a controller for the login form:

Then, enable the form login authenticator using the form_login setting:

YAML
XML
PHP

Note

The login_path and check_path support URLs and route names (simply cannot have mandatory wildcards - e.g. /login/{foo} where foo has no default value).

Once enabled, the security arrangement redirects unauthenticated visitors to the login_path when they try to access a secured identify (this behavior can exist customized using authentication entry points).

Edit the login controller to return the login form:

Don't permit this controller misfile you. Its job is just to render the course: the form_login authenticator volition handle the form submission automatically. If the user submits an invalid email or password, that authenticator will store the error and redirect back to this controller, where nosotros read the error (using AuthenticationUtils) and so that it can exist displayed back to the user.

Finally, create or update the template:

Caution

The mistake variable passed into the template is an instance of AuthenticationException. Information technology may contain sensitive information almost the authentication failure. Never utilize fault.bulletin: employ the messageKey property instead, as shown in the example. This message is always safe to brandish.

The form can expect like anything, but it usually follows some conventions:

The <form> element sends a POST request to the login route, since that'south what yous configured as the check_path under the form_login key in security.yaml;
The username (or whatever your user'due south "identifier" is, like an email) field has the proper name _username and the password field has the name _password.

Caution

This login course is currently not protected against CSRF attacks. Read Security on how to protect your login course.

And that's it! When you submit the form, the security organisation automatically reads the _username and _password Post parameter, loads the user via the user provider, checks the user's credentials and either authenticates the user or sends them dorsum to the login form where the error can be displayed.

To review the whole process:

The user tries to access a resource that is protected (e.g. /admin);
The firewall initiates the authentication process past redirecting the user to the login form (/login);
The /login page renders login grade via the road and controller created in this example;
The user submits the login grade to /login;
The security system (i.e. the form_login authenticator) intercepts the request, checks the user'south submitted credentials, authenticates the user if they are correct, and sends the user back to the login class if they are not.

Login CSRF attacks can exist prevented using the same technique of adding hidden CSRF tokens into the login forms. The Security component already provides CSRF protection, merely you lot need to configure some options before using it.

First, you need to enable CSRF on the form login:

YAML
XML
PHP

So, apply the csrf_token() function in the Twig template to generate a CSRF token and store information technology equally a hidden field of the grade. By default, the HTML field must be chosen _csrf_token and the string used to generate the value must be authenticate:

After this, you lot have protected your login grade against CSRF attacks.

Some applications provide an API that is secured using tokens. These applications may utilize an endpoint that provides these tokens based on a username (or email) and countersign. The JSON login authenticator helps you lot create this functionality.

Enable the authenticator using the json_login setting:

YAML
XML
PHP

Annotation

The check_path supports URLs and route names (but cannot take mandatory wildcards - e.g. /login/{foo} where foo has no default value).

The authenticator runs when a client request the check_path. Commencement, create a controller for this path:

This login controller will be called after the authenticator successfully authenticates the user. You can get the authenticated user, generate a token (or whatsoever you demand to return) and render the JSON response:

Annotation

The #[CurrentUser] can only be used in controller arguments to retrieve the authenticated user. In services, you would use getUser().

That'southward information technology! To summarize the process:

A customer (e.thousand. the front end-stop) makes a POST request with the Content-Type: application/json header to /api/login with username (even if your identifier is actually an email) and password keys:
The security system intercepts the request, checks the user's submitted credentials and authenticates the user. If the credentials is wrong, an HTTP 401 Unauthorized JSON response is returned, otherwise your controller is run;
Your controller creates the right response:

HTTP Bones

HTTP Bones authentication is a standardized HTTP authentication framework. It asks credentials (username and password) using a dialog in the browser and the HTTP basic authenticator of Symfony will verify these credentials.

Add together the http_basic primal to your firewall to enable HTTP Basic authentication:

YAML
XML
PHP

That'southward it! Whenever an unauthenticated user tries to visit a protected page, Symfony will inform the browser that it needs to start HTTP bones hallmark (using the WWW-Cosign response header). And so, the authenticator verifies the credentials and authenticates the user.

Note

You cannot use log out with the HTTP bones authenticator. Even if you log out from Symfony, your browser "remembers" your credentials and will ship them on every request.

Login links are a passwordless hallmark mechanism. The user will receive a brusk-lived link (e.g. via email) which will authenticate them to the website.

Yous can learn all about this authenticator in How to use Passwordless Login Link Authentication.

10.509 Client Certificates

When using client certificates, your spider web server does all the hallmark itself. The X.509 authenticator provided by Symfony extracts the electronic mail from the "distinguished name" (DN) of the client document. Then, it uses this e-mail as user identifier in the user provider.

First, configure your web server to enable client certificate verification and to expose the document's DN to the Symfony application:

Nginx
Apache

Then, enable the X.509 authenticator using x509 on your firewall:

YAML
XML
PHP

Past default, Symfony extracts the email address from the DN in two different ways:

First, it tries the SSL_CLIENT_S_DN_Email server parameter, which is exposed by Apache;
If it is non ready (east.grand. when using Nginx), it uses SSL_CLIENT_S_DN and matches the value following emailAddress=.

You can customize the name of both parameters nether the x509 key. See the configuration reference for more details.

Remote Users

Likewise client certificate authentication, there are more spider web server modules that pre-authenticate a user (e.g. kerberos). The remote user authenticator provides a bones integration for these services.

These modules often betrayal the authenticated user in the REMOTE_USER surroundings variable. The remote user authenticator uses this value equally the user identifier to load the respective user.

Enable remote user hallmark using the remote_user key:

YAML
XML
PHP

Symfony provides basic protection confronting brute force login attacks. You must enable this using the login_throttling setting:

YAML
XML
PHP

Past default, login attempts are limited on max_attempts (default: 5) failed requests for IP address + username and v * max_attempts failed requests for IP address. The 2nd limit protects confronting an attacker using multiple usernames from bypassing the kickoff limit, without disrupting normal users on big networks (such as offices).

Tip

Limiting the failed login attempts is only one basic protection against animate being forcefulness attacks. The OWASP Brute Force Attacks guidelines mention several other protections that you lot should consider depending on the level of protection required.

If you need a more complex limiting algorithm, create a class that implements RequestRateLimiterInterface (or use DefaultLoginRateLimiter) and set the limiter option to its service ID:

YAML
XML
PHP

Logging Out

To enable logging out, actuate the logout config parameter under your firewall:

YAML
XML
PHP

Next, you lot need to create a route for this URL (but non a controller):

Annotations
Attributes
YAML
XML

That'southward it! By sending a user to the app_logout road (i.e. to /logout) Symfony volition un-authenticate the current user and redirect them.

Customizing Logout

In some cases you demand to run extra logic upon logout (e.g. invalidate some tokens) or want to customize what happens later a logout. During logout, a LogoutEvent is dispatched. Annals an event listener or subscriber to run custom logic. The following data is available in the event form:

getToken(): Returns the security token of the session that is virtually to exist logged out.
getRequest(): Returns the current request.
getResponse(): Returns a response, if information technology is already fix by a custom listener. Apply setResponse() to configure a custom logout response.

Fetching the User Object

After authentication, the User object of the current user can be accessed via the getUser() shortcut in the base controller:

Fetching the User from a Service

If you need to get the logged in user from a service, use the Security service:

Users can now log in to your app using your login form. Great! Now, y'all demand to learn how to deny access and work with the User object. This is called authorization, and its job is to decide if a user tin can access some resource (a URL, a model object, a method phone call, ...).

The procedure of authorisation has two different sides:

The user receives a specific office when logging in (e.g. ROLE_ADMIN).
You add code so that a resource (e.g. URL, controller) requires a specific "attribute" (e.k. a role like ROLE_ADMIN) in social club to be accessed.

Roles

When a user logs in, Symfony calls the getRoles() method on your User object to determine which roles this user has. In the User grade that was generated earlier, the roles are an assortment that'south stored in the database and every user is ever given at least i role: ROLE_USER:

This is a nice default, only y'all tin can practise whatever yous want to determine which roles a user should have. Here are a few guidelines:

Every function must offset with ROLE_ (otherwise, things won't work as expected)
Other than the above rule, a office is just a cord and you can invent what you need (e.grand. ROLE_PRODUCT_ADMIN).

You'll apply these roles side by side to grant access to specific sections of your site.

Hierarchical Roles

Instead of giving many roles to each user, you can define role inheritance rules past creating a office hierarchy:

YAML
XML
PHP

Users with the ROLE_ADMIN role will also have the ROLE_USER part. Users with ROLE_SUPER_ADMIN, will automatically accept ROLE_ADMIN, ROLE_ALLOWED_TO_SWITCH and ROLE_USER (inherited from ROLE_ADMIN).

Caution

For role bureaucracy to work, do not use $user->getRoles() manually. For example, in a controller extending from the base controller:

Note

The role_hierarchy values are static - you tin't, for example, store the role hierarchy in a database. If you need that, create a custom security voter that looks for the user roles in the database.

Add Lawmaking to Deny Access

In that location are 2 ways to deny access to something:

access_control in security.yaml allows you to protect URL patterns (due east.g. /admin/*). Simpler, only less flexible;
in your controller (or other code).

Securing URL patterns (access_control)

The most basic way to secure role of your app is to secure an entire URL pattern in security.yaml. For example, to require ROLE_ADMIN for all URLs that get-go with /admin, y'all can:

YAML
XML
PHP

You can define as many URL patterns as yous need - each is a regular expression. Merely, only one will be matched per request: Symfony starts at the top of the list and stops when information technology finds the first friction match:

YAML
XML
PHP

Prepending the path with ^ means that only URLs beginning with the pattern are matched. For example, a path of /admin (without the ^) would match /admin/foo just would as well match URLs like /foo/admin.

Each access_control can as well lucifer on IP accost, hostname and HTTP methods. It can besides be used to redirect a user to the https version of a URL pattern. Come across How Does the Security access_control Piece of work?.

Securing Controllers and other Code

You tin can deny access from inside a controller:

That's it! If access is non granted, a special AccessDeniedException is thrown and no more code in your controller is chosen. And then, one of two things will happen:

If the user isn't logged in yet, they will be asked to log in (eastward.one thousand. redirected to the login folio).
If the user is logged in, only does non accept the ROLE_ADMIN role, they'll be shown the 403 admission denied folio (which yous can customize).

Thanks to the SensioFrameworkExtraBundle, you can also secure your controller using annotations:

Annotations
Attributes

For more information, see the FrameworkExtraBundle documentation.

Access Control in Templates

If you want to bank check if the electric current user has a certain role, y'all can apply the built-in is_granted() helper function in any Twig template:

Securing other Services

You lot can cheque access anywhere in your code by injecting the Security service. For example, suppose y'all accept a SalesReportManager service and you want to include actress details only for users that have a ROLE_SALES_ADMIN part:

If you're using the default services.yaml configuration, Symfony will automatically pass the security.helper to your service thanks to autowiring and the Security type-hint.

You lot can also utilize a lower-level AuthorizationCheckerInterface service. It does the same thing every bit Security, but allows you to type-hint a more-specific interface.

Allowing Unsecured Admission (i.east. Anonymous Users)

When a visitor isn't still logged in to your website, they are treated as "unauthenticated" and don't have any roles. This will block them from visiting your pages if you defined an access_control rule.

In the access_control configuration, yous can use the PUBLIC_ACCESS security attribute to exclude some routes for unauthenticated access (e.yard. the login page):

YAML
XML
PHP

Granting Bearding Users Access in a Custom Voter

If you're using a custom voter, you tin can allow anonymous users admission by checking if at that place is no user set on the token:

Setting Individual User Permissions

Most applications require more specific admission rules. For case, a user should be able to but edit their own comments on a blog. Voters permit y'all to write whatever business logic you need to decide access. Using these voters is like to the role-based access checks implemented in the previous chapters. Read How to Utilise Voters to Bank check User Permissions to learn how to implement your own voter.

Checking to meet if a User is Logged In (IS_AUTHENTICATED_FULLY)

If you lot only want to check if a user is logged in (you lot don't care about roles), you have the following two options.

Firstly, if y'all've given every user ROLE_USER, you can bank check for that function.

Secondly, you lot can utilise a special "attribute" in place of a role:

You tin utilize IS_AUTHENTICATED_FULLY anywhere roles are used: like access_control or in Twig.

IS_AUTHENTICATED_FULLY isn't a role, but it kind of acts similar one, and every user that has logged in will accept this. Actually, there are some special attributes like this:

IS_AUTHENTICATED_REMEMBERED: All logged in users have this, even if they are logged in considering of a "call up me cookie". Even if you don't use the remember me functionality, you can utilise this to bank check if the user is logged in.
IS_AUTHENTICATED_FULLY: This is similar to IS_AUTHENTICATED_REMEMBERED, but stronger. Users who are logged in just because of a "remember me cookie" will have IS_AUTHENTICATED_REMEMBERED but volition not accept IS_AUTHENTICATED_FULLY.
IS_REMEMBERED: Just users authenticated using the remember me functionality, (i.e. a remember-me cookie).
IS_IMPERSONATOR: When the electric current user is impersonating another user in this session, this attribute will match.

Understanding how Users are Refreshed from the Session

At the end of every asking (unless your firewall is stateless), your User object is serialized to the session. At the beginning of the adjacent asking, it's deserialized and then passed to your user provider to "refresh" it (e.g. Doctrine queries for a fresh user).

Then, the two User objects (the original from the session and the refreshed User object) are "compared" to run across if they are "equal". By default, the core AbstractToken course compares the return values of the getPassword(), getSalt() and getUserIdentifier() methods. If any of these are different, your user will exist logged out. This is a security measure to brand sure that malicious users can be de-authenticated if core user data changes.

Nonetheless, in some cases, this process can cause unexpected authentication problems. If you're having problems authenticating, information technology could exist that you lot are authenticating successfully, simply y'all immediately lose authentication after the first redirect.

In that case, review the serialization logic (e.one thousand. the __serialize() or serialize() methods) on you lot user form (if y'all have any) to brand sure that all the fields necessary are serialized and also exclude all the fields not necessary to be serialized (e.grand. Doctrine relations).

Comparing Users Manually with EquatableInterface

Or, if you need more control over the "compare users" process, brand your User class implement EquatableInterface. Then, your isEqualTo() method volition be called when comparing users instead of the core logic.

Security Events

During the hallmark process, multiple events are dispatched that permit you to hook into the process or customize the response sent back to the user. You lot can practise this by creating an event listener or subscriber for these events.

Tip

Every Security firewall has its own result dispatcher (security.event_dispatcher.FIREWALLNAME). Events are dispatched on both the global and the firewall-specific dispatcher. You tin can register on the firewall dispatcher if yous want your listener to only be called for a specific firewall. For instance, if you have an api and main firewall, use this configuration to annals only on the logout event in the main firewall:

YAML
XML
PHP

Authentication Events

CheckPassportEvent: Dispatched later on the authenticator created the security passport. Listeners of this event do the actual hallmark checks (like checking the passport, validating the CSRF token, etc.)
AuthenticationTokenCreatedEvent: Dispatched later on the passport was validated and the authenticator created the security token (and user). This can be used in advanced use-cases where y'all need to modify the created token (e.one thousand. for multi cistron authentication).
AuthenticationSuccessEvent: Dispatched when authentication is nearing success. This is the last event that tin can make an authentication fail by throwing an AuthenticationException.
LoginSuccessEvent: Dispatched later authentication was fully successful. Listeners to this event tin modify the response sent dorsum to the user.
LoginFailureEvent: Dispatched after an AuthenticationException was thrown during authentication. Listeners to this event tin can modify the error response sent back to the user.

Often Asked Questions

Can I have Multiple Firewalls?: Yep! But it's ordinarily non necessary. Each firewall is like a divide security arrangement, beingness authenticated in i firewall doesn't make you authenticated in some other one. One firewall can have multiple diverse means of allowing authentication (e.g. form login, API key authentication and LDAP).
Can I Share Authentication Between Firewalls?: Yes, but only with some configuration. If you're using multiple firewalls and you lot authenticate against 1 firewall, yous will non be authenticated against any other firewalls automatically. Unlike firewalls are like unlike security systems. To do this you have to explicitly specify the same Security Configuration Reference (SecurityBundle) for different firewalls. However, ane chief firewall is usually sufficient for the needs of nigh applications.
Security doesn't seem to work on my Error Pages: Equally routing is done before security, 404 error pages are not covered by whatsoever firewall. This means you can't check for security or even admission the user object on these pages. Run across How to Customize Error Pages for more details.
My Authentication Doesn't Seem to Piece of work: No Errors, just I'g Never Logged In: Sometimes authentication may be successful, just afterward redirecting, you lot're logged out immediately due to a problem loading the User from the session. To encounter if this is an effect, check your log file (var/log/dev.log) for the log bulletin:
Cannot refresh token considering user has inverse: If yous run across this, there are two possible causes. First, in that location may exist a trouble loading your User from the session. Come across Security. Second, if certain user data was inverse in the database since the last page refresh, Symfony will purposely log out the user for security reasons.

Where Are Passwords Stored In Symfony For Services

Security

Security

The User

Loading the User: The User Provider

Registering the User: Hashing Passwords

The Firewall

Authenticating Users

HTTP Bones

10.509 Client Certificates

Remote Users

Logging Out

Customizing Logout

Fetching the User Object

Fetching the User from a Service

Roles

Hierarchical Roles

Add Lawmaking to Deny Access

Securing URL patterns (access_control)

Securing Controllers and other Code

Access Control in Templates

Securing other Services

Allowing Unsecured Admission (i.east. Anonymous Users)

Granting Bearding Users Access in a Custom Voter

Setting Individual User Permissions

Checking to meet if a User is Logged In (IS_AUTHENTICATED_FULLY)

Understanding how Users are Refreshed from the Session

Comparing Users Manually with EquatableInterface

Security Events

Authentication Events

Often Asked Questions