Merge pull request #3446 from esl/auth-config-sections

Section-based auth config

big_tests/test.config

@@ -238,7 +238,7 @@
   workers = 10"}]},
     {pgsql_mnesia,
      [{dbs, [redis, pgsql]},
-      {auth_method, "\"rdbms\""},
+      {auth_method, "rdbms"},
       {outgoing_pools, "[outgoing_pools.redis.global_distrib]
   scope = \"global\"
   workers = 10
@@ -260,7 +260,7 @@
       {mod_roster, "  backend = \"rdbms\"\n"}]},
     {odbc_mssql_mnesia,
      [{dbs, [redis, mssql]},
-      {auth_method, "\"rdbms\""},
+      {auth_method, "rdbms"},
       {rdbms_server_type, "\"mssql\""},
       {outgoing_pools, "[outgoing_pools.redis.global_distrib]
   scope = \"global\"
@@ -277,7 +277,7 @@
     {mysql_redis,
      [{dbs, [redis, mysql, rmq]},
       {sm_backend, "\"redis\""},
-      {auth_method, "\"rdbms\""},
+      {auth_method, "rdbms"},
       {outgoing_pools, "[outgoing_pools.redis.global_distrib]
   scope = \"global\"
   workers = 10
@@ -302,7 +302,7 @@
       {mod_roster, "  backend = \"rdbms\"\n"}]},
     {ldap_mnesia,
      [{dbs, [redis, ldap]},
-      {auth_method, "\"ldap\""},
+      {auth_method, "ldap"},
       {outgoing_pools, "[outgoing_pools.redis.global_distrib]
   scope = \"global\"
   workers = 10
@@ -329,15 +329,15 @@
   connection.tls.certfile = \"priv/ssl/fake_cert.pem\"
   connection.tls.keyfile = \"priv/ssl/fake_key.pem\""},
       {password_format, "password.format = \"scram\""},
-      {auth_ldap, "ldap.base = \"ou=Users,dc=esl,dc=com\"
-  ldap.filter = \"(objectClass=inetOrgPerson)\""},
+      {auth_method_opts, "base = \"ou=Users,dc=esl,dc=com\"
+    filter = \"(objectClass=inetOrgPerson)\""},
       {mod_vcard, "  backend = \"ldap\"
   host = \"vjud.@HOST@\"
   ldap_base = \"ou=Users,dc=esl,dc=com\"
   ldap_filter = \"(objectClass=inetOrgPerson)\"\n"}]},
     {riak_mnesia,
      [{dbs, [redis, riak]},
-      {auth_method, "\"riak\""},
+      {auth_method, "riak"},
       %% Specify a list of ciphers to avoid
       %% "no function clause matching tls_v1:enum_to_oid(28)" error
       %% on Riak's side running with Erlang R16.

big_tests/tests/sasl_external_SUITE.erl

@@ -149,7 +149,8 @@ modify_config_and_restart(CyrsaslExternalConfig, Config) ->
                   "just_tls" -> escalus_config:get_config(ssl_options, Config, "") ++ VerifyMode;
                   "fast_tls" -> ""
               end,
-    AuthMethods = escalus_config:get_config(auth_methods, Config, [{auth_method, "\"pki\""}]),
+    AuthMethods = escalus_config:get_config(auth_methods, Config,
+                                            [{auth_method, "pki"}, {auth_method_opts, false}]),
     CACertFile = filename:join([path_helper:repo_dir(Config),
                                 "tools", "ssl", "ca-clients", "cacert.pem"]),
     NewConfigValues = [{tls_config, "tls.module = \"" ++ TLSModule ++ "\"\n"

doc/authentication-methods/anonymous.md

@@ -25,10 +25,7 @@ Specifies the SASL mechanisms supported by the `anonymous` authentication method
 ### Example
 
 ```toml
-[auth]
-  methods = ["anonymous"]
-
-  [auth.anonymous]
-    allow_multiple_connections = true
-    protocol = "both"
+[auth.anonymous]
+  allow_multiple_connections = true
+  protocol = "both"
 ```

doc/authentication-methods/dummy.md

@@ -29,8 +29,7 @@ where `Base` is `base_time` and `Variance` is `variance`, as configured below.
 ### Example
 
 ```toml
-[auth]
-  methods = ["dummy"]
-  dummy.base = 5
-  dummy.variance = 10
+[auth.dummy]
+  base = 5
+  variance = 10
 ```

doc/authentication-methods/external.md

@@ -41,10 +41,7 @@ Specifies the number of workers serving external authentication requests.
 ### Example
 
 ```toml
-[auth]
-  methods = ["external"]
-
-  [auth.external]
-    program = "/home/user/authenticator"
-    instances = 5
+[auth.external]
+  program = "/home/user/authenticator"
+  instances = 5
 ```

doc/authentication-methods/http.md

@@ -23,11 +23,8 @@ Optional HTTP Basic Authentication in format `"username:password"` - used to aut
 Authentication:
 
 ```toml
-[auth]
-  methods = ["http"]
-
-  [auth.http]
-    basic_auth = "mongooseim:DzviNQw3qyGJDrJDu+ClyA"
+[auth.http]
+  basic_auth = "mongooseim:DzviNQw3qyGJDrJDu+ClyA"
 ```
 
 Outgoing pools:

doc/authentication-methods/jwt.md

@@ -40,11 +40,8 @@ Name of the JWT key that contains the user name to verify.
 ### Example
 
 ```toml
-[auth]
-  methods = ["jwt"]
-
-  [auth.jwt]
-    secret.value = "top-secret123"
-    algorithm = "HS256"
-    username_key = "user"
+[auth.jwt]
+  secret.value = "top-secret123"
+  algorithm = "HS256"
+  username_key = "user"
 ```

doc/authentication-methods/ldap.md

@@ -140,10 +140,7 @@ Specifies whether or not to dereference aliases: `finding` means to dereference
 ### Example
 
 ```toml
-[auth]
-  methods = ["ldap"]
-
-  [auth.ldap]
-    base = "ou=Users,dc=example,dc=com"
-    filter = "(objectClass=inetOrgPerson)"
+[auth.ldap]
+  base = "ou=Users,dc=example,dc=com"
+  filter = "(objectClass=inetOrgPerson)"
 ```

doc/authentication-methods/pki.md

@@ -4,10 +4,10 @@ This is a simple authentication method, meant to be used with the `SASL EXTERNAL
 It simply accepts all usernames as long as they are validated by the SASL logic.
 
 !!! Warning
-    
+
     Some of its callbacks return hardcoded values, as it's impossible for this backend to properly acquire certain pieces of information.
     These include:
-    
+
     | Function | Hardcoded value | Explanation |
     | ---------- | ----------------- | ----------- |
     | `does_user_exist` | `true` | PKI reponds with `true` to modules checking if user's interlocutor actually exists so e.g. messages to nonexistent users will always be stored by `mod_mam`. This is not necessarily a security threat but something to be aware of. |
@@ -16,3 +16,9 @@ It simply accepts all usernames as long as they are validated by the SASL logic.
 ## Configuration options
 
 None.
+
+## Example
+
+```toml
+[auth.pki]
+```

doc/authentication-methods/rdbms.md

@@ -23,11 +23,8 @@ Enabling this option makes MongooseIM use an alternative query that might be not
 Authentication:
 
 ```toml
-[auth]
-  methods = ["rdbms"]
-
-  [auth.rdbms]
-    users_number_estimate = true
+[auth.rdbms]
+  users_number_estimate = true
 ```
 
 Outgoing pools:

doc/authentication-methods/riak.md

@@ -20,11 +20,8 @@ Bucket type for storing users in Riak.
 Authentication:
 
 ```toml
-[auth]
-  methods = ["riak"]
-
-  [auth.riak]
-    bucket_type = "user"
+[auth.riak]
+  bucket_type = "user"
 ```
 
 Outgoing pools:

doc/configuration/auth.md

@@ -1,4 +1,4 @@
-The `auth` section is used to choose and configure the **methods** which are used by MongooseIM to authenticate connecting users.
+The `auth` section is used to choose and configure the **method** which is used by MongooseIM to authenticate connecting users.
 The following methods are supported:
 
 * `internal` - stores the user accounts in an internal Mnesia database,
@@ -12,23 +12,31 @@ The following methods are supported:
 * [`pki`](../authentication-methods/pki.md) - uses the certificate provided by the user to authenticate them,
 * [`dummy`](../authentication-methods/dummy.md) - no authentication, only for development and testing.
 
-To enable user connections, you need to set up at least one of the methods listed above (see `auth.methods` below).
-Some methods have more complex setup procedures - the method names above are links to their descriptions,
-which list their specific configuration options. The general options are described below.
+To allow the users to connect, you need to choose the authentication method from the list above and enable it by adding a corresponding section. For example, the default configuration file has the `[auth.internal]` section, which enables the `internal` method, using the internal Mnesia database to store users and their passwords. However, for production systems other methods like `rdbms` are recommended, as using an external database offers easier maintenance, flexibility, scalability and configurability in a typical setup. Some methods have more complex setup procedures and have their own specific options - the method names above are links to their descriptions. There are some general authentication options as well, which are described below.
+
+!!! Warning
+    Make sure that the compatible SASL mechanisms are enabled, see [capabilities](#authentication-method-capabilities).
 
 ## General Options
 
-The options listed here are used to configure the authentication methods.
+The options listed here affect more than one configuration method.
 
 ### `auth.methods`
 * **Syntax:** array of strings. Allowed values: `"internal"`, `"rdbms"`, `"external"`, `"anonymous"`, `"ldap"`, `"jwt"`, `"riak"`, `"http"`, `"pki"`, `"dummy"`
 * **Default:** not set
 * **Example:** `methods = ["internal", "anonymous"]`
 
-Specifies the methods used to authenticate connecting users. Methods from the list are queried one after another until one of them replies positively. By default there are no methods, so nobody can authenticate.
+It is possible to enable more than one method - they are queried one by one in the alphabetical order until one of them succeeds or there are no more methods. You can change the default order by using this option. Make sure that all methods from the list have their corresponding sections included in the `auth` section, e.g.
 
-!!! Warning
-    Make sure that the compatible SASL mechanisms are enabled, see [capabilities](#authentication-method-capabilities).
+```toml
+[auth]
+  methods = ["internal", "dummy"]
+
+  [auth.internal]
+
+  [auth.dummy]
+    variance = 1000
+```
 
 ### `auth.sasl_mechanisms`
 * **Syntax:** array of strings. Allowed values: `"scram_sha512_plus"`, `"scram_sha512"`, `"scram_sha384_plus"`, `"scram_sha384"`, `"scram_sha256_plus"`, `"scram_sha256"`, `"scram_sha224_plus"`, `"scram_sha224"`, `"scram_sha1_plus"`, `"scram_sha1"`, `"plain"`, `"anonymous"`, `"oauth"`, `"external"`, `"digest"`
@@ -38,8 +46,8 @@ Specifies the methods used to authenticate connecting users. Methods from the li
 Specifies the list of allowed SASL mechanisms, which are announced during stream negotiation and eventually enforced (users can't pick a mechanism not listed here).
 
 !!! Notes
-    
-    * This list is still filtered by [capabilities](#authentication-method-capabilities).
+
+    * This list is still filtered by [capabilities](#authentication-method-capabilities). For example, if you use the `internal` method, only the `PLAIN`, `DIGEST-MD5` and `SCRAM-SHA-*` mechanisms from the list will be supported. If there are no compatible mechanisms on the list, the users will not be able to authenticate.
     * Configuring the `sasl_mechanisms` replaces the default list entirely.
     * The order in which the mechanisms are listed in the config will be taken as the order in which they are advertised.
     * All `SCRAM-SHA-*` mechanisms (specified as `scram_sha*`) have their counterparts which support channel binding and are advertised as separate authentication mechanisms suffixed by `-PLUS` (specified as `scram_sha*_plus`).
@@ -60,6 +68,7 @@ The table below shows the supported SASL mechanisms (columns) for each authentic
 | riak      |   x   |   x    |     x      |           |          |
 | http      |   x   |   x    |     x      |           |          |
 | pki       |       |        |            |           |    x     |
+| dummy     |   x   |        |            |           |          |
 
 ### `auth.sasl_external`
 * **Syntax:** list of strings, allowed values: `"standard"`, `"common_name"`, `"auth_id"`
@@ -99,9 +108,12 @@ MongooseIM supports SHA-1, SHA-224, SHA-256, SHA-384 and SHA-512 for SCRAM hashi
 You can use this option to limit the supported hash functions by listing them explicitly.
 The value `"sha"` stands for the SHA-1 algorithm.
 
+!!! Warning
+    This option limits the supported `SCRAM-SHA-*` SASL mechanisms to the ones compatible with the specified hash functions.
+
 ### `auth.scram_iterations`
 * **Syntax:** positive integer
-* **Default:** 10000,  as recommended in this [XEP](https://xmpp.org/extensions/xep-0438.html#pbkdf2) and this [NIST Guidelines](https://pages.nist.gov/800-63-3/sp800-63b.html#sec5)
+* **Default:** 10000, as recommended in this [XEP](https://xmpp.org/extensions/xep-0438.html#pbkdf2) and this [NIST Guidelines](https://pages.nist.gov/800-63-3/sp800-63b.html#sec5)
 * **Example:** `scram_iterations = 20_000`
 
 Hash function round count.
@@ -111,18 +123,25 @@ But it adds load on both client and server, so this parameter should be tuned as
 Note that increasing the security of a password has a higher impact over the security of the algorithm, without impacting its load.
 See more information in this [NIST guide, Appendix A.2.2](https://csrc.nist.gov/publications/detail/sp/800-132/final)
 
-## Example
+## Examples
 
-This minimal authentication setup uses the internal Mnesia database to store users and their passwords:
+Internal authentication method without any general options - you can skip the `auth` section in this case:
 
 ```toml
-[auth]
-  methods = ["internal"]
+[auth.internal]
 ```
 
-According to the [capabilities](#authentication-method-capabilities) of the `internal` method, the `PLAIN`, `DIGEST-MD5` and `SCRAM-SHA-*` mechanisms will be supported.
+Internal authentication method with some general options:
+
+```toml
+[auth]
+  password.hash = ["sha512"]
+  scram_iterations = 20000
+
+  [auth.internal]
+```
 
-However, for production systems other methods like `rdbms` are recommended, as using an external database offers easier maintenance, flexibility, scalability and configurability in a typical setup.
+For more specific examples, see the links below.
 
 ## Method-specific options
 

doc/migrations/5.0.0_5.1.0.md

@@ -0,0 +1,11 @@
+## Configuration changes
+
+The configuration format has slightly changed and you might need to amend `mongooseim.toml`.
+
+### Section `auth`
+
+Each authentication method needs a TOML section, e.g. if you have the `rdbms` method enabled, you need to have the `[auth.rdbms]` section in the configuration file, even if it is empty. The `methods` option is not required anymore and especially if you are using only one method, you can remove it. See the [configuration](../configuration/auth.md) for details.
+
+### Section `host_config`
+
+The rules for overriding global options in the `host_config` section have been simplified. The `auth` section and the `s2s.address`, `s2s.domain_certfile` and `s2s.shared` options now completely override the corresponding general settings instead of being merged with them.

mkdocs.yml

@@ -181,6 +181,7 @@ nav:
       - '4.0.1 to 4.1.0': 'migrations/4.0.1_4.1.0.md'
       - '4.1.0 to 4.2.0': 'migrations/4.1.0_4.2.0.md'
       - '4.2.0 to 5.0.0': 'migrations/4.2.0_5.0.0.md'
+      - '5.0.0 to 5.1.0': 'migrations/5.0.0_5.1.0.md'
       - 'MAM MUC migration helper': 'migrations/jid-from-mam-muc-script.md'
   - 'Contributions to the Ecosystem': 'Contributions.md'
   - 'MongooseIM History': 'History.md'

rel/files/mongooseim.toml

@@ -162,20 +162,23 @@
 {{/listen_service}}
 
 [auth]
-  {{#auth_ldap}}
-  {{{auth_ldap}}}
-  {{/auth_ldap}}
-  methods = [{{{auth_method}}}]
   {{#password_format}}
   {{{password_format}}}
   {{/password_format}}
   {{#scram_iterations}}
   scram_iterations = {{{scram_iterations}}}
   {{/scram_iterations}}
+  {{#cyrsasl_external}}
   sasl_external = [{{{cyrsasl_external}}}]
+  {{/cyrsasl_external}}
   {{#sasl_mechanisms}}
   sasl_mechanisms = [{{{sasl_mechanisms}}}]
   {{/sasl_mechanisms}}
+  {{#auth_method}}
+
+  [auth.{{{auth_method}}}]{{#auth_method_opts}}
+    {{{auth_method_opts}}}{{/auth_method_opts}}
+  {{/auth_method}}
 
 {{#outgoing_pools}}
 {{{outgoing_pools}}}
@@ -395,8 +398,7 @@
 #[[host_config]]
 #  host = "anonymous.localhost"
 #
-#  [host_config.auth]
-#    methods = ["anonymous"]
-#    anonymous.allow_multiple_connections = true
-#    anonymous.protocol = "both"
+#  [host_config.auth.anonymous]
+#    allow_multiple_connections = true
+#    protocol = "both"
 {{/host_config}}