Documentation Home
MySQL 5.7 Reference Manual
Related Documentation Download this Manual
PDF (US Ltr) - 37.9Mb
PDF (A4) - 38.0Mb
PDF (RPM) - 37.3Mb
HTML Download (TGZ) - 10.3Mb
HTML Download (Zip) - 10.3Mb
HTML Download (RPM) - 8.9Mb
Man Pages (TGZ) - 216.7Kb
Man Pages (Zip) - 329.5Kb
Info (Gzip) - 3.4Mb
Info (Zip) - 3.4Mb
Excerpts from this Manual

MySQL 5.7 Reference Manual  /  ...  /  Pluggable Authentication System Variables

6.5.1.12 Pluggable Authentication System Variables

These variables are unavailable unless the appropriate server-side plugin is installed:

  • authentication_ldap_sasl for system variables with names of the form authentication_ldap_sasl_xxx

  • authentication_ldap_simple for system variables with names of the form authentication_ldap_simple_xxx

  • authentication_ldap_sasl_auth_method_name

    Introduced5.7.19
    Command-Line Format--authentication-ldap-sasl-auth-method-name=value
    System VariableNameauthentication_ldap_sasl_auth_method_name
    Variable ScopeGlobal
    Dynamic VariableYes
    Permitted ValuesTypestring
    DefaultSCRAM-SHA-1

    For SASL LDAP authentication, the authentication method name. Communication between the authentication plugin and the LDAP server occurs according to this authentication method. These authentication method values are permitted:

    • SCRAM-SHA-1: Authentication uses a SASL challenge-response mechanism to ensure password security.

      The client-side authentication_ldap_sasl_client plugin communicates with the SASL server, using the password to create a challenge and obtain a SASL request buffer, then passes this buffer to the server-side authentication_ldap_sasl plugin. The client-side and server-side SASL LDAP plugins use SASL messages for secure transmission of credentials within the LDAP protocol, to avoid sending the clear-text password between the MySQL client and server.

  • authentication_ldap_sasl_bind_base_dn

    Introduced5.7.19
    Command-Line Format--authentication-ldap-sasl-bind-base-dn=value
    System VariableNameauthentication_ldap_sasl_bind_base_dn
    Variable ScopeGlobal
    Dynamic VariableYes
    Permitted ValuesTypestring
    DefaultNULL

    For SASL LDAP authentication, the base distinguished name (DN). This variable can be used to limit the scope of searches by anchoring them at a certain location (the base) within the search tree.

    Suppose that members of one set of LDAP user entries each have this form:

    uid=user_name,pwd=user_password,ou=People,dc=example,dc=com

    And that members of another set of LDAP user entries each have this form:

    uid=user_name,pwd=user_password,ou=Admin,dc=example,dc=com

    Then searches work like this for different base DN values:

    • If the base DN is ou=People,dc=example,dc=com: Searches find user entries only in the first set.

    • If the base DN is ou=Admin,dc=example,dc=com: Searches find user entries only in the second set.

    • If the base DN is ou=dc=example,dc=com: Searches find user entries in the first or second set.

    In general, more specific base DN values result in faster searches because they limit the search scope more.

  • authentication_ldap_sasl_bind_root_dn

    Introduced5.7.19
    Command-Line Format--authentication-ldap-sasl-bind-root-dn=value
    System VariableNameauthentication_ldap_sasl_bind_root_dn
    Variable ScopeGlobal
    Dynamic VariableYes
    Permitted ValuesTypestring
    DefaultNULL

    For SASL LDAP authentication, the root distinguished name (DN). This variable is used in conjunction with authentication_ldap_sasl_bind_root_pwd as the credentials for authenticating to the LDAP server for the purpose of performing searches. Authentication uses either one or two LDAP bind operations, depending on whether the the MySQL account names an LDAP user DN:

    • If the account does not name a user DN: authentication_ldap_sasl performs an initial LDAP binding using authentication_ldap_sasl_bind_root_dn and authentication_ldap_sasl_bind_root_pwd. (These are both empty by default, so if they are not set, the LDAP server must permit anonymous connections.) The resulting bind LDAP handle is used to search for the user DN, based on the client user name. authentication_ldap_sasl performs a second bind using the user DN and client-supplied password.

    • If the account does name a user DN: The first bind operation is unnecessary in this case. authentication_ldap_sasl performs a single bind using the user DN and client-supplied password. This is faster than if the MySQL account does not specify an LDAP user DN.

  • authentication_ldap_sasl_bind_root_pwd

    Introduced5.7.19
    Command-Line Format--authentication-ldap-sasl-bind-root-pwd=value
    System VariableNameauthentication_ldap_sasl_bind_root_pwd
    Variable ScopeGlobal
    Dynamic VariableYes
    Permitted ValuesTypestring
    DefaultNULL

    For SASL LDAP authentication, the password for the root distinguished name. This variable is used in conjunction with authentication_ldap_sasl_bind_root_dn. See the description of that variable.

  • authentication_ldap_sasl_ca_path

    Introduced5.7.19
    Command-Line Format--authentication-ldap-sasl-ca-path=value
    System VariableNameauthentication_ldap_sasl_ca_path
    Variable ScopeGlobal
    Dynamic VariableYes
    Permitted ValuesTypestring
    DefaultNULL

    For SASL LDAP authentication, the absolute path of the certificate authority file. Specify this file if it is desired that the authentication plugin perform verification of the LDAP server certificate.

    Note

    In addition to setting the authentication_ldap_sasl_ca_path variable to the file name, you must add the appropriate certificate authority certificates to the file.

  • authentication_ldap_sasl_group_search_attr

    Introduced5.7.19
    Command-Line Format--authentication-ldap-sasl-group-search-attr=value
    System VariableNameauthentication_ldap_sasl_group_search_attr
    Variable ScopeGlobal
    Dynamic VariableYes
    Permitted ValuesTypestring
    Defaultcn

    For SASL LDAP authentication, the name of the attribute that specifies group names in LDAP directory entries. If authentication_ldap_sasl_group_search_attr has its default value of cn, searches return the cn value as the group name. For example, if an LDAP entry with a uid value of user1 has a cn attribute of mygroup, searches for user1 return mygroup as the group name.

  • authentication_ldap_sasl_init_pool_size

    Introduced5.7.19
    Command-Line Format--authentication-ldap-sasl-init-pool-size=value
    System VariableNameauthentication_ldap_sasl_init_pool_size
    Variable ScopeGlobal
    Dynamic VariableYes
    Permitted ValuesTypeinteger
    Default10
    Min Value0
    Max Value32767

    For SASL LDAP authentication, the initial size of the pool of connections to the LDAP server. Choose the value for this variable based on the average number of concurrent authentication requests to the LDAP server.

    The plugin uses authentication_ldap_sasl_init_pool_size and authentication_ldap_sasl_max_pool_size together for connection-pool management:

    • When the authentication plugin initializes, it creates authentication_ldap_sasl_init_pool_size connections, unless authentication_ldap_sasl_max_pool_size=0 to disable pooling.

    • If the plugin receives an anthentication request when there are no free connections in the current connection pool, the plugin can create a new connection, up to the maximum connection pool size given by authentication_ldap_sasl_max_pool_size.

    • If the plugin receives a request when the pool size is already at its maximum and there are no free connections, authentication fails.

    • When the plugin unloads, it closes all pooled connections.

    Changes to plugin system variable settings may have no effect on connections already in the pool. For example, modifying the LDAP server host, port, or TLS settings does not affect existing connections. However, if the original variable values were invalid and the connection pool could not be initialized, the plugin attempts to reinitialize the pool for the next LDAP request. In this case, the new system variable values are used for the reinitialization attempt.

    If authentication_ldap_sasl_max_pool_size=0 to disable pooling, each LDAP connection opened by the plugin uses the values the system variables have at that time.

  • authentication_ldap_sasl_log_status

    Introduced5.7.19
    Command-Line Format--authentication-ldap-sasl-log-status=value
    System VariableNameauthentication_ldap_sasl_log_status
    Variable ScopeGlobal
    Dynamic VariableYes
    Permitted ValuesTypeinteger
    Default1
    Min Value1
    Max Value5

    For SASL LDAP authentication, the logging level. The following table shows the permitted level values and their meanings.

    Table 6.19 Log Levels for authentication_ldap_sasl_log_status

    Option Value Types of Messages Logged
    1 No messages
    2 Error messages
    3 Error and warning messages
    4 Error, warning, and information messages
    5 All messages

    On the client side, messages can be logged to the standard output by setting the AUTHENTICATION_LDAP_CLIENT_LOG environment variable. The permitted and default values are the same as for authentication_ldap_sasl_log_status.

    The AUTHENTICATION_LDAP_CLIENT_LOG environment variable applies only to SASL LDAP authentication. It has no effect for simple LDAP authentication because the client plugin in that case is mysql_clear_password, which knows nothing about LDAP operations.

  • authentication_ldap_sasl_max_pool_size

    Introduced5.7.19
    Command-Line Format--authentication-ldap-sasl-max-pool-size=value
    System VariableNameauthentication_ldap_sasl_max_pool_size
    Variable ScopeGlobal
    Dynamic VariableYes
    Permitted ValuesTypeinteger
    Default1000
    Min Value0
    Max Value32767

    For SASL LDAP authentication, the maximum size of the pool of connections to the LDAP server. To disable connection pooling, set this variable to 0.

    This variable is used in conjunction with authentication_ldap_sasl_init_pool_size. See the description of that variable.

  • authentication_ldap_sasl_server_host

    Introduced5.7.19
    Command-Line Format--authentication-ldap-sasl-server-host=value
    System VariableNameauthentication_ldap_sasl_server_host
    Variable ScopeGlobal
    Dynamic VariableYes
    Permitted ValuesTypestring

    For SASL LDAP authentication, the LDAP server host. The permitted values for this variable depend on the authentication method:

  • authentication_ldap_sasl_server_port

    Introduced5.7.19
    Command-Line Format--authentication-ldap-sasl-server-port=value
    System VariableNameauthentication_ldap_sasl_server_port
    Variable ScopeGlobal
    Dynamic VariableYes
    Permitted ValuesTypeinteger
    Default389
    Min Value1
    Max Value32376

    For SASL LDAP authentication, the LDAP server TCP/IP port number.

  • authentication_ldap_sasl_tls

    Introduced5.7.19
    Command-Line Format--authentication-ldap-sasl-tls=value
    System VariableNameauthentication_ldap_sasl_tls
    Variable ScopeGlobal
    Dynamic VariableYes
    Permitted ValuesTypeboolean
    DefaultOFF

    For SASL LDAP authentication, whether connections by the plugin to the LDAP server are secure. If this variable is enabled, the plugin uses TLS to connect securely to the LDAP server. If you enable this variable, you may also wish to set the authentication_ldap_sasl_ca_path variable.

    MySQL LDAP plugins support the StartTLS method, which initializes TLS on top of a plain LDAP connection. The ldaps method is deprecated and MySQL does not support it.

  • authentication_ldap_sasl_user_search_attr

    Introduced5.7.19
    Command-Line Format--authentication-ldap-sasl-user-search-attr=value
    System VariableNameauthentication_ldap_sasl_user_search_attr
    Variable ScopeGlobal
    Dynamic VariableYes
    Permitted ValuesTypestring
    Defaultuid

    For SASL LDAP authentication, the name of the attribute that specifies user names in LDAP directory entries. If a user distinguished name is not provided, the authentication plugin searches for the name using this attribute. For example, if the authentication_ldap_sasl_user_search_attr value is uid, a search for the user name user1 finds entries with a uid value of user1.

  • authentication_ldap_simple_auth_method_name

    Introduced5.7.19
    Command-Line Format--authentication-ldap-simple-auth-method-name=value
    System VariableNameauthentication_ldap_simple_auth_method_name
    Variable ScopeGlobal
    Dynamic VariableYes
    Permitted ValuesTypestring
    DefaultSIMPLE

    For simple LDAP authentication, the authentication method name. Communication between the authentication plugin and the LDAP server occurs according to this authentication method. These authentication method values are permitted:

    • SIMPLE: This authentication method uses either one or two LDAP bind operations, depending on whether the the MySQL account names an LDAP user distinguished name. See the description of authentication_ldap_simple_bind_root_dn.

    • AD-FOREST: authentication_ldap_simple searches all the domains in the Active Directory forest, performing an LDAP bind to each Active Directory domain until the user is found in some domain.

  • authentication_ldap_simple_bind_base_dn

    Introduced5.7.19
    Command-Line Format--authentication-ldap-simple-bind-base-dn=value
    System VariableNameauthentication_ldap_simple_bind_base_dn
    Variable ScopeGlobal
    Dynamic VariableYes
    Permitted ValuesTypestring
    DefaultNULL

    For simple LDAP authentication, the base distinguished name (DN). This variable can be used to limit the scope of searches by anchoring them at a certain location (the base) within the search tree.

    Suppose that members of one set of LDAP user entries each have this form:

    uid=user_name,pwd=user_password,ou=People,dc=example,dc=com

    And that members of another set of LDAP user entries each have this form:

    uid=user_name,pwd=user_password,ou=Admin,dc=example,dc=com

    Then searches work like this for different base DN values:

    • If the base DN is ou=People,dc=example,dc=com: Searches find user entries only in the first set.

    • If the base DN is ou=Admin,dc=example,dc=com: Searches find user entries only in the second set.

    • If the base DN is ou=dc=example,dc=com: Searches find user entries in the first or second set.

    In general, more specific base DN values result in faster searches because they limit the search scope more.

  • authentication_ldap_simple_bind_root_dn

    Introduced5.7.19
    Command-Line Format--authentication-ldap-simple-bind-root-dn=value
    System VariableNameauthentication_ldap_simple_bind_root_dn
    Variable ScopeGlobal
    Dynamic VariableYes
    Permitted ValuesTypestring
    DefaultNULL

    For simple LDAP authentication, the root distinguished name (DN). This variable is used in conjunction with authentication_ldap_simple_bind_root_pwd as the credentials for authenticating to the LDAP server for the purpose of performing searches. Authentication uses either one or two LDAP bind operations, depending on whether the the MySQL account names an LDAP user DN:

    • If the account does not name a user DN: authentication_ldap_simple performs an initial LDAP binding using authentication_ldap_simple_bind_root_dn and authentication_ldap_simple_bind_root_pwd. (These are both empty by default, so if they are not set, the LDAP server must permit anonymous connections.) The resulting bind LDAP handle is used to search for the user DN, based on the client user name. authentication_ldap_simple performs a second bind using the user DN and client-supplied password.

    • If the account does name a user DN: The first bind operation is unnecessary in this case. authentication_ldap_simple performs a single bind using the user DN and client-supplied password. This is faster than if the MySQL account does not specify an LDAP user DN.

  • authentication_ldap_simple_bind_root_pwd

    Introduced5.7.19
    Command-Line Format--authentication-ldap-simple-bind-root-pwd=value
    System VariableNameauthentication_ldap_simple_bind_root_pwd
    Variable ScopeGlobal
    Dynamic VariableYes
    Permitted ValuesTypestring
    DefaultNULL

    For simple LDAP authentication, the password for the root distinguished name. This variable is used in conjunction with authentication_ldap_simple_bind_root_dn. See the description of that variable.

  • authentication_ldap_simple_ca_path

    Introduced5.7.19
    Command-Line Format--authentication-ldap-simple-ca-path=value
    System VariableNameauthentication_ldap_simple_ca_path
    Variable ScopeGlobal
    Dynamic VariableYes
    Permitted ValuesTypestring
    DefaultNULL

    For simple LDAP authentication, the absolute path of the certificate authority file. Specify this file if it is desired that the authentication plugin perform verification of the LDAP server certificate.

    Note

    In addition to setting the authentication_ldap_simple_ca_path variable to the file name, you must add the appropriate certificate authority certificates to the file.

  • authentication_ldap_simple_group_search_attr

    Introduced5.7.19
    Command-Line Format--authentication-ldap-simple-group-search-attr=value
    System VariableNameauthentication_ldap_simple_group_search_attr
    Variable ScopeGlobal
    Dynamic VariableYes
    Permitted ValuesTypestring
    Defaultcn

    For simple LDAP authentication, the name of the attribute that specifies group names in LDAP directory entries. If authentication_ldap_simple_group_search_attr has its default value of cn, searches return the cn value as the group name. For example, if an LDAP entry with a uid value of user1 has a cn attribute of mygroup, searches for user1 return mygroup as the group name.

  • authentication_ldap_simple_init_pool_size

    Introduced5.7.19
    Command-Line Format--authentication-ldap-simple-init-pool-size=value
    System VariableNameauthentication_ldap_simple_init_pool_size
    Variable ScopeGlobal
    Dynamic VariableYes
    Permitted ValuesTypeinteger
    Default10
    Min Value0
    Max Value32767

    For simple LDAP authentication, the initial size of the pool of connections to the LDAP server. Choose the value for this variable based on the average number of concurrent authentication requests to the LDAP server.

    The plugin uses authentication_ldap_simple_init_pool_size and authentication_ldap_simple_max_pool_size together for connection-pool management:

    • When the authentication plugin initializes, it creates authentication_ldap_simple_init_pool_size connections, unless authentication_ldap_simple_max_pool_size=0 to disable pooling.

    • If the plugin receives an anthentication request when there are no free connections in the current connection pool, the plugin can create a new connection, up to the maximum connection pool size given by authentication_ldap_simple_max_pool_size.

    • If the plugin receives a request when the pool size is already at its maximum and there are no free connections, authentication fails.

    • When the plugin unloads, it closes all pooled connections.

    Changes to plugin system variable settings may have no effect on connections already in the pool. For example, modifying the LDAP server host, port, or TLS settings does not affect existing connections. However, if the original variable values were invalid and the connection pool could not be initialized, the plugin attempts to reinitialize the pool for the next LDAP request. In this case, the new system variable values are used for the reinitialization attempt.

    If authentication_ldap_simple_max_pool_size=0 to disable pooling, each LDAP connection opened by the plugin uses the values the system variables have at that time.

  • authentication_ldap_simple_log_status

    Introduced5.7.19
    Command-Line Format--authentication-ldap-simple-log-status=value
    System VariableNameauthentication_ldap_simple_log_status
    Variable ScopeGlobal
    Dynamic VariableYes
    Permitted ValuesTypeinteger
    Default1
    Min Value1
    Max Value5

    For simple LDAP authentication, the logging level. The following table shows the permitted level values and their meanings.

    Table 6.20 Log Levels for authentication_ldap_simple_log_status

    Option Value Types of Messages Logged
    1 No messages
    2 Error messages
    3 Error and warning messages
    4 Error, warning, and information messages
    5 All messages

  • authentication_ldap_simple_max_pool_size

    Introduced5.7.19
    Command-Line Format--authentication-ldap-simple-max-pool-size=value
    System VariableNameauthentication_ldap_simple_max_pool_size
    Variable ScopeGlobal
    Dynamic VariableYes
    Permitted ValuesTypeinteger
    Default1000
    Min Value0
    Max Value32767

    For simple LDAP authentication, the maximum size of the pool of connections to the LDAP server. To disable connection pooling, set this variable to 0.

    This variable is used in conjunction with authentication_ldap_simple_init_pool_size. See the description of that variable.

  • authentication_ldap_simple_server_host

    Introduced5.7.19
    Command-Line Format--authentication-ldap-simple-server-host=value
    System VariableNameauthentication_ldap_simple_server_host
    Variable ScopeGlobal
    Dynamic VariableYes
    Permitted ValuesTypestring

    For simple LDAP authentication, the LDAP server host. The permitted values for this variable depend on the authentication method:

    • For authentication_ldap_simple_auth_method_name=SIMPLE: The LDAP server host can be a host name or IP address.

    • For authentication_ldap_simple_auth_method_name=AD-FOREST. The LDAP server host can be an Active Directory domain name. For example, for an LDAP server URL of ldap://example.mem.local:389, the server name can be mem.local.

      An Active Directory forest setup can have multiple domains (LDAP server IPs), which can be discovered using DNS. On Unix and Unix-like systems, some additional setup may be required to configure your DNS server with SRV records that specify the LDAP servers for the Active Directory domain. Suppose that your configuration has these properties:

      • The name server that provides information about Active Directory domains has IP address 10.172.166.100.

      • The LDAP servers have names ldap1.mem.local through ldap3.mem.local and IP addresses 10.172.166.101 through 10.172.166.103.

      You want the LDAP servers to be discoverable using SRV searches. For example, at the command line, a command like this should list the LDAP servers:

      host -t SRV _ldap._tcp.mem.local

      Perform the DNS configuration as follows:

      1. Add a line to /etc/resolv.conf to specify the name server that provides information about Active Directory domains:

        nameserver 10.172.166.100
      2. Configure the appropriate zone file for the name server with SRV records for the LDAP servers:

        _ldap._tcp.mem.local. 86400 IN SRV 0 100 389 ldap1.mem.local.
        _ldap._tcp.mem.local. 86400 IN SRV 0 100 389 ldap2.mem.local.
        _ldap._tcp.mem.local. 86400 IN SRV 0 100 389 ldap3.mem.local.
      3. It may also be necessary to specify the IP address for the LDAP servers in /etc/hosts if the server host cannot be resolved. For example, add lines like this to the file:

        10.172.166.101 ldap1.mem.local
        10.172.166.102 ldap2.mem.local
        10.172.166.103 ldap3.mem.local

      With the DNS configured as just described, the server-side LDAP plugin can discover the LDAP servers and will try to authenticate in all domains until authentication succeeds or there are no more servers.

      Windows needs no such settings as just described. Given the LDAP server host in the authentication_ldap_simple_server_host value, the Windows LDAP library searches all domains and attempts to authenticate.

  • authentication_ldap_simple_server_port

    Introduced5.7.19
    Command-Line Format--authentication-ldap-simple-server-port=value
    System VariableNameauthentication_ldap_simple_server_port
    Variable ScopeGlobal
    Dynamic VariableYes
    Permitted ValuesTypeinteger
    Default389
    Min Value1
    Max Value32376

    For simple LDAP authentication, the LDAP server TCP/IP port number.

  • authentication_ldap_simple_tls

    Introduced5.7.19
    Command-Line Format--authentication-ldap-simple-tls=value
    System VariableNameauthentication_ldap_simple_tls
    Variable ScopeGlobal
    Dynamic VariableYes
    Permitted ValuesTypeboolean
    DefaultOFF

    For simple LDAP authentication, whether connections by the plugin to the LDAP server are secure. If this variable is enabled, the plugin uses TLS to connect securely to the LDAP server. If you enable this variable, you may also wish to set the authentication_ldap_simple_ca_path variable.

    MySQL LDAP plugins support the StartTLS method, which initializes TLS on top of a plain LDAP connection. The ldaps method is deprecated and MySQL does not support it.

  • authentication_ldap_simple_user_search_attr

    Introduced5.7.19
    Command-Line Format--authentication-ldap-simple-user-search-attr=value
    System VariableNameauthentication_ldap_simple_user_search_attr
    Variable ScopeGlobal
    Dynamic VariableYes
    Permitted ValuesTypestring
    Defaultuid

    For simple LDAP authentication, the name of the attribute that specifies user names in LDAP directory entries. If a user distinguished name is not provided, the authentication plugin searches for the name using this attribute. For example, if the authentication_ldap_simple_user_search_attr value is uid, a search for the user name user1 finds entries with a uid value of user1.


User Comments
Sign Up Login You must be logged in to post a comment.