安全配置参考 (SecurityBundle)

编辑此页

SecurityBundle 集成了 Symfony 应用程序中的 安全组件。所有这些选项都在你的应用程序配置中的 security 键下配置。

1
2
3
4
5
# displays the default config values defined by Symfony
$ php bin/console config:dump-reference security

# displays the actual config values used by your application
$ php bin/console debug:config security

注意

当使用 XML 时，你必须使用 http://symfony.ac.cn/schema/dic/security 命名空间，相关的 XSD schema 可在以下位置找到：http://symfony.ac.cn/schema/dic/services/services-1.0.xsd

配置

基本选项:

高级选项:

其中一些选项定义了数十个子选项，它们在单独的文章中进行了解释

access_denied_url

类型: string 默认: null

定义用户在 403 HTTP 错误后被重定向到的 URL（除非你定义了自定义的访问拒绝处理器）。示例：/no-permission

delete_cookies

类型: array 默认: []

列出用户注销时要删除的 cookie 的名称（和其他可选功能）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# config/packages/security.yaml
security:
    # ...

    firewalls:
        main:
            # ...
            logout:
                delete_cookies:
                    cookie1-name: null
                    cookie2-name:
                        path: '/'
                    cookie3-name:
                        path: null
                        domain: example.com

erase_credentials

类型: boolean 默认: true

如果 true，则在身份验证后调用用户对象的 eraseCredentials() 方法。

hide_user_not_found

类型: boolean 默认: true

如果 true，当找不到用户时，会抛出一个通用异常，类型为 BadCredentialsException，消息为“Bad credentials”。

如果 false，则抛出的异常类型为 UserNotFoundException，并且包含给定的未找到的用户标识符。

session_fixation_strategy

类型: string 默认: SessionAuthenticationStrategy::MIGRATE

Session Fixation 是一种安全攻击，允许攻击者劫持有效的用户会话。在用户身份验证时不分配新会话 ID 的应用程序容易受到此攻击。

此选项的可能值是

access_control

定义你的应用程序 URL 的安全保护。例如，它用于在尝试访问后端时触发用户身份验证，并允许未经身份验证的用户访问登录表单页面。

此选项在 Security access_control 如何工作？中详细解释。

firewalls

这可以说是安全配置文件中最重要的选项。它定义了用于你的应用程序的每个 URL（或 URL 模式）的身份验证机制

1
2
3
4
5
6
7
8
9
10
11
# config/packages/security.yaml
security:
    # ...
    firewalls:
        # 'main' is the name of the firewall (can be chosen freely)
        main:
            # 'pattern' is a regular expression matched against the incoming
            # request URL. If there's a match, authentication is triggered
            pattern: ^/admin
            # the rest of options depend on the authentication mechanism
            # ...

另请参阅

阅读本文，了解如何通过主机和 HTTP 方法限制防火墙。

除了某些通用配置选项外，最重要的防火墙选项取决于身份验证机制，它可以是以下任何一种

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
# config/packages/security.yaml
security:
    # ...
    firewalls:
        main:
            # ...
                x509:
                    # ...
                remote_user:
                    # ...
                guard:
                    # ...
                form_login:
                    # ...
                form_login_ldap:
                    # ...
                json_login:
                    # ...
                http_basic:
                    # ...
                http_basic_ldap:
                    # ...
                http_digest:
                    # ...

你可以使用 debug:firewall 命令查看有关你的应用程序中防火墙的实际信息

1
2
3
4
5
6
7
8
9
# displays a list of firewalls currently configured for your application
$ php bin/console debug:firewall

# displays the details of a specific firewall
$ php bin/console debug:firewall main

# displays the details of a specific firewall, including detailed information
# about the event listeners for the firewall
$ php bin/console debug:firewall main --events

form_login 认证

当在防火墙下使用 form_login 身份验证监听器时，有几个通用选项用于配置“表单登录”体验。有关更多详细信息，请参阅自定义表单登录验证器响应。

login_path

类型: string 默认: /login

这是用户将被重定向到的路由或路径（除非 use_forward 设置为 true），当他们尝试访问受保护的资源但未完全通过身份验证时。

此路径必须可由普通的、未经身份验证的用户访问，否则你可能会创建一个重定向循环。

check_path

类型: string 默认: /login_check

这是你的登录表单必须提交到的路由或路径。防火墙将拦截任何 (POST 请求，默认情况下仅限) 到此 URL 的请求，并处理提交的登录凭据。

确保此 URL 包含在你的主防火墙中（即，不要仅为 check_path URL 创建单独的防火墙）。

failure_path

类型: string 默认: /login

这是用户在登录尝试失败后被重定向到的路由或路径。它可以是相对/绝对 URL 或 Symfony 路由名称。

form_only

类型: boolean 默认: false

将此选项设置为 true 以要求登录数据使用表单发送（它检查请求内容类型是否为 application/x-www-form-urlencoded 或 multipart/form-data）。这对于例如防止 表单登录验证器 响应应由 JSON 登录验证器 处理的请求非常有用。

use_forward

类型: boolean 默认: false

如果你希望用户被转发到登录表单而不是被重定向，请将此选项设置为 true。

username_parameter

类型: string 默认: _username

这是你的登录表单的用户名字段的名称。当你将表单提交到 check_path 时，安全系统将查找具有此名称的 POST 参数。

password_parameter

类型: string 默认: _password

这是你的登录表单的密码字段的名称。当你将表单提交到 check_path 时，安全系统将查找具有此名称的 POST 参数。

post_only

类型: boolean 默认: true

默认情况下，你必须将登录表单作为 POST 请求提交到 check_path URL。通过将此选项设置为 false，你也可以发送 GET 请求。

与登录后重定向相关的选项

always_use_default_target_path

类型: boolean 默认: false

如果 true，则用户始终被重定向到默认目标路径，而与会话中存储的先前 URL 无关。

default_target_path

类型: string 默认: /

当会话中没有存储先前的页面时（例如，当用户直接浏览登录页面时），用户将被重定向到的页面。

target_path_parameter

类型: string 默认: _target_path

当使用登录表单时，如果你包含一个 HTML 元素来设置目标路径，则此选项允许你更改 HTML 元素本身的名称。

failure_path_parameter

类型: string 默认: _failure_path

当使用登录表单时，如果你包含一个 HTML 元素来设置失败路径，则此选项允许你更改 HTML 元素本身的名称。

use_referer

类型: boolean 默认: false

如果 true，当会话中没有存储先前的 URL 时，用户将被重定向到 HTTP_REFERER 标头中存储的值。如果引用 URL 与使用 login_path 路由生成的 URL 相同，则用户将被重定向到 default_target_path 以避免重定向循环。

注意

由于历史原因，并且为了匹配 HTTP 标准的拼写错误，该选项被称为 use_referer 而不是 use_referrer。

logout

你可以配置注销选项。

delete_cookies

类型: array 默认: []

列出用户注销时要删除的 cookie 的名称（和其他可选功能）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# config/packages/security.yaml
security:
    # ...

    firewalls:
        main:
            # ...
            logout:
                delete_cookies:
                    cookie1-name: null
                    cookie2-name:
                        path: '/'
                    cookie3-name:
                        path: null
                        domain: example.com

clear_site_data

类型: array 默认: []

Clear-Site-Data HTTP 标头清除与请求网站关联的浏览数据（cookie、存储、缓存）。它允许 Web 开发人员更好地控制客户端浏览器为其来源存储的数据。

允许的值为 cache、cookies、storage 和 executionContexts。也可以使用 * 作为所有指令的通配符

1
2
3
4
5
6
7
8
9
10
11
# config/packages/security.yaml
security:
    # ...

    firewalls:
        main:
            # ...
            logout:
                clear_site_data:
                    - cookies
                    - storage

invalidate_session

类型: boolean 默认: true

默认情况下，当用户从任何防火墙注销时，他们的会话将失效。这意味着从一个防火墙注销会自动将他们从所有其他防火墙注销。

invalidate_session 选项允许重新定义此行为。在每个防火墙中将此选项设置为 false，用户将仅从当前防火墙注销，而不是从其他防火墙注销。

path

类型: string 默认: /logout

触发注销的路径。你需要设置一个具有匹配路径的路由。

target

类型: string 默认: /

注销后重定向到的相对路径（如果值以 / 开头），或绝对 URL（如果以 http:// 或 https:// 开头），或路由名称（否则）。

enable_csrf

类型: boolean 默认: null

将此选项设置为 true 以在使用 Symfony 的默认 CSRF 令牌管理器在注销过程中启用 CSRF 保护。如果你需要使用自定义 CSRF 令牌管理器，也请设置 csrf_token_manager 选项。

csrf_parameter

类型: string 默认: _csrf_token

存储 CSRF 令牌值的参数名称。

csrf_token_manager

类型: string 默认: null

用于生成 CSRF 令牌的服务的 id。Symfony 提供了一个默认服务，其 ID 为 security.csrf.token_manager。

csrf_token_id

类型: string 默认: logout

用于标识令牌（并在之后检查其有效性）的任意字符串。

JSON 登录认证

check_path

类型: string 默认: /login_check

这是系统必须发布到的 URL 或路由名称，以使用 JSON 验证器进行身份验证。路径必须由用户将要进行身份验证的防火墙覆盖。

username_path

类型: string 默认: username

使用此选项和 password_path 来修改 JSON 验证器的预期请求体结构。例如，如果 JSON 文档具有以下结构

1
2
3
4
5
6
7
8
{
    "security": {
        "credentials": {
            "login": "dunglas",
            "password": "MyPassword"
        }
    }
}

安全配置应为

1
2
3
4
5
6
7
8
9
10
11
# config/packages/security.yaml
security:
    # ...

    firewalls:
        main:
            lazy: true
            json_login:
                check_path:    login
                username_path: security.credentials.login
                password_path: security.credentials.password

password_path

类型: string 默认: password

使用此选项来修改预期的请求体结构。有关更多详细信息，请参阅 username_path。

LDAP 认证

有几个选项可用于连接到 LDAP 服务器，使用 form_login_ldap、http_basic_ldap 和 json_login_ldap 身份验证提供程序或 ldap 用户提供程序。

有关更多详细信息，请参阅 针对 LDAP 服务器进行身份验证。

认证

您可以使用 form_login、http_basic 和 json_login 认证提供程序的 LDAP 变体来向 LDAP 服务器进行身份验证。使用 form_login_ldap、http_basic_ldap 和 json_login_ldap，它们将尝试对 LDAP 服务器执行 bind 操作，而不是使用密码比较。

这两种身份验证提供程序都具有与其普通版本相同的参数，此外还增加了两个配置键：

service

type: string default: ldap

这是您配置的 LDAP 客户端的名称。

dn_string

type: string default: {user_identifier}

这是将用作 bind DN 的字符串。{user_identifier} 占位符将被用户提供的值（他们的登录名）替换。根据您的 LDAP 服务器的配置，您可能需要覆盖此值。

query_string

类型: string 默认: null

这是将用于查询 DN 的字符串。{user_identifier} 占位符将被用户提供的值（他们的登录名）替换。根据您的 LDAP 服务器的配置，您将需要覆盖此值。只有当无法使用 dn_string 配置选项静态派生用户的 DN 时，此设置才是必要的。

用户提供程序

用户仍然会从配置的用户提供程序中获取。如果您希望从 LDAP 服务器获取用户，您将需要使用 LDAP 用户提供程序 以及以下任何身份验证提供程序：form_login_ldap 或 http_basic_ldap 或 json_login_ldap。

X.509 认证

1
2
3
4
5
6
7
8
9
10
11
12
# config/packages/security.yaml
security:
    # ...

    firewalls:
        main:
            # ...
            x509:
                provider:        your_user_provider
                user:            SSL_CLIENT_S_DN_Email
                credentials:     SSL_CLIENT_S_DN
                user_identifier: emailAddress

user

type: string default: SSL_CLIENT_S_DN_Email

这是包含用于在 Symfony 中加载用户的用户标识符的 $_SERVER 参数的名称。默认值由 Apache 公开。

credentials

type: string default: SSL_CLIENT_S_DN

如果 user 参数不可用，则这是包含证书的完整“专有名称”（例如，由 Nginx 公开）的 $_SERVER 参数的名称。

默认情况下，Symfony 识别此参数中 emailAddress= 后面的值。可以使用 user_identifier 选项更改此设置。

user_identifier

type: string default: emailAddress

此选项的值告诉 Symfony 使用哪个参数在“专有名称”中查找用户标识符。

例如，如果“专有名称”是 Subject: C=FR, O=My Organization, CN=user1, [email protected]，并且此选项的值是 'CN'，则用户标识符将是 'user1'。

远程用户认证

1
2
3
4
5
6
7
8
# config/packages/security.yaml
security:
    firewalls:
        main:
            # ...
            remote_user:
                provider: your_user_provider
                user:     REMOTE_USER

provider

type: string

应该由此身份验证器使用的用户提供程序的 Service ID。

user

type: string default: REMOTE_USER

这是保存用户标识符的 $_SERVER 参数的名称。

Firewall Context

如果您的应用程序使用多个 防火墙，您会注意到，如果您在一个防火墙中通过了身份验证，您不会在另一个防火墙中自动通过身份验证。换句话说，这些系统不共享一个公共的“上下文”：每个防火墙都像一个独立的安全性系统。

但是，每个防火墙都有一个可选的 context 键（默认为防火墙的名称），该键在将安全性数据存储到会话以及从会话中检索安全性数据时使用。如果多个防火墙将此键设置为相同的值，“上下文”实际上可以共享

1
2
3
4
5
6
7
8
9
10
11
# config/packages/security.yaml
security:
    # ...

    firewalls:
        somename:
            # ...
            context: my_context
        othername:
            # ...
            context: my_context

注意

防火墙上下文键存储在会话中，因此每个使用它的防火墙都必须将其 stateless 选项设置为 false。否则，上下文将被忽略，您将无法同时在多个防火墙上进行身份验证。

stateless

防火墙可以配置 stateless 布尔值选项，以声明在对用户进行身份验证时不得使用会话

1
2
3
4
5
6
7
8
# config/packages/security.yaml
security:
    # ...

    firewalls:
        main:
            # ...
            stateless: true

用户检查器

在用户身份验证期间，可能需要额外的检查来验证是否允许经过身份验证的用户登录。每个防火墙都可以包含一个 user_checker 选项，以定义用于执行这些检查的服务。

了解有关用户检查器的更多信息，请参阅 如何创建和启用自定义用户检查器。

必需的徽章

防火墙可以配置必须在经过身份验证的护照上存在的要求徽章列表

1
2
3
4
5
6
7
8
# config/packages/security.yaml
security:
    # ...

    firewalls:
        main:
            # ...
            required_badges: ['CsrfTokenBadge', 'My\Badge']

providers

此选项定义如何加载应用程序用户（从数据库、LDAP 服务器、配置文件等）。阅读 用户提供程序 以了解有关这些提供程序的更多信息。

role_hierarchy

此选项允许您通过创建角色层次结构来定义角色继承规则，而不是将许多角色与用户关联，如 安全性 中所述。

本作品，包括代码示例，根据 Creative Commons BY-SA 3.0 许可获得许可。
TOC
    版本