.. -*- coding: utf-8 -*-

*******************
Authentication
*******************

- There is a `user_list.yml` mechanism to authenticate web mode access users.
- This section describes how to use `user_list.yml`.

Configuration items in `user_list.yml`
========================================

.. code-block:: yaml

    users:                         # A list of users, each of which is a map that contains the following fields.
    - uid: 1                       # An ID that identifies a user. No two users can have the same ID.
      name: admin                  # A name that identifies the user. No two users can have the same name.
      password: XXXXXXXXXXX        # The user's password. The value is hashed with the hash function specified in the next hash field.
      hash: plain                  # The hash function used to hash the password, which can be plain, md5, sha1, or sha256, or oauth2.
      groups: [admin]              # A list of groups to which the user belongs, as specified in the groups field.
      email: admin@aaa.bbb.jp      # The email address of the user, used when authenticating using the provider specified in the oauth2 field.
    - uid: 101
      name: user01
      password: XXXXXXXXXXX
      hash: md5
      groups: [user]
      email: user01@aaa.bbb.jp
    - uid: 102
      name: user02
      password: XXXXXXXXXXX
      hash: sha1
      groups: [readonly]
      email: user02@aaa.bbb.jp
    - uid: 103
      name: user03
      password: XXXXXXXXXXX
      hash: sha256
      groups: [editor]
      email: user03@aaa.bbb.jp
    groups:                        # A list of groups, each of which is a map that contains the following fields.
    - gid: 1                       # An ID that identifies a group. No two groups can have the same ID.
      name: admin                  # A name that identifies the group. No two groups can have the same name.
    - gid: 2
      name: guest
    - gid: 101
      name: user
    - gid: 102
      name: readonly
      parent: user                 # The parent group of the group. If the parent group is not specified, the group is a top-level group.
    - gid: 103
      name: editor
      parent: user
    cmdrule:                       # A list of command rules, Specify a rule that determines whether or not a command is executable when executed by a user in web mode.
      policy: deny                 # Specify the default policy for the rule. The value can be allow or deny.
      rules:                       # Specify rules to allow or deny execution of the command, depending on the group the user belongs to.
      - groups: [admin]
        rule: allow
      - groups: [user]             # Specify the groups to which the rule applies.
        mode: client               # Specify the "mode" as the condition for applying the rule.
        cmds: [file_download, file_list, server_info] # Specify the "cmd" to which the rule applies. Multiple items can be specified in a list.
        rule: allow                # Specifies whether or not the specified command is allowed for the specified group. The value can be allow or deny.
      - groups: [user]
        mode: server
        cmds: [list]
        rule: allow
      - groups: [user, guest]
        mode: web
        cmds: [genpass]
        rule: allow
      - groups: [editor]
        mode: client
        cmds: [file_copy, file_mkdir, file_move, file_remove, file_rmdir, file_upload]
        rule: allow
    pathrule:                      # List of RESTAPI rules, rules that determine whether or not a RESTAPI can be executed when a user in web mode accesses it.
      policy: deny                 # Specify the default policy for the rule. The value can be allow or deny.
      rules:                       # Specify rules to allow or deny execution of the RESTAPI, depending on the group the user belongs to.
      - groups: [admin]            # Specify the groups to which the rule applies.
        paths: [/]                 # Specify the "path" to which the rule applies. Multiple items can be specified in a list.
        rule: allow                # Specifies whether or not the specified RESTAPI is allowed for the specified group. The value can be allow or deny.
      - groups: [guest]
        paths: [/signin, /assets, /copyright, /dosignin, /dosignout, /password/change,
                /gui, /get_server_opt, /usesignout, /versions_cmdbox, /versions_used]
        rule: allow
      - groups: [user]
        paths: [/signin, /assets, /bbforce_cmd, /copyright, /dosignin, /dosignout, /password/change,
                /exec_cmd, /exec_pipe, /filer, /gui, /get_server_opt, /usesignout, /versions_cmdbox, /versions_used]
        rule: allow
      - groups: [readonly]
        paths: [/gui/del_cmd, /gui/del_pipe, /gui/save_cmd, /gui/save_pipe]
        rule: deny
      - groups: [editor]
        paths: [/gui/del_cmd, /gui/del_pipe, /gui/save_cmd, /gui/save_pipe]
        rule: allow
    password:                       # Password settings.
      policy:                       # Password policy settings.
        enabled: true               # Specify whether or not to enable password policy.
        not_same_before: true       # Specify whether or not to allow the same password as the previous one.
        min_length: 16              # Specify the minimum length of the password.
        max_length: 64              # Specify the maximum length of the password.
        min_lowercase: 1            # Specify the minimum number of lowercase letters in the password.
        min_uppercase: 1            # Specify the minimum number of uppercase letters in the password.
        min_digit: 1                # Specify the minimum number of digits in the password.
        min_symbol: 1               # Specify the minimum number of symbol characters in the password.
        not_contain_username: true  # Specify whether or not to include the username in the password.
      expiration:                   # Password expiration settings.
        enabled: true               # Specify whether or not to enable password expiration.
        period: 90                  # Specify the number of days after which the password will expire.
        notify: 7                   # Specify the number of days before the password expires that a notification will be sent.
      lockout:                      # Account lockout settings.
        enabled: true               # Specify whether or not to enable account lockout.
        threshold: 5                # Specify the number of failed login attempts before the account is locked.
        reset: 30                   # Specify the number of minutes after which the failed login count will be reset.
    oauth2:                             # OAuth2 settings.
      providers:                        # This is a per-provider setting for OAuth2.
        google:                         # Google's OAuth2 configuration.
          enabled: false                # Specify whether to enable Google's OAuth2.
          client_id: XXXXXXXXXXX        # Specify Google's OAuth2 client ID.
          client_secret: XXXXXXXXXXX    # Specify Google's OAuth2 client secret.
          redirect_uri: https://localhost:8443/oauth2/google/callback # Specify Google's OAuth2 redirect URI.
          scope: ['email']              # Specify the scope you want to retrieve with Google's OAuth2. Usually, just reading the email is sufficient.
          signin_module:                # Specify the module name that implements the sign-in. see, cmdbox.app.signin.SignIn
          note:                         # Specify a description such as Google's OAuth2 reference site.
          - https://developers.google.com/identity/protocols/oauth2/web-server?hl=ja#httprest
        github:                         # OAuth2 settings for GitHub.
          enabled: false                # Specify whether to enable OAuth2 for GitHub.
          client_id: XXXXXXXXXXX        # Specify the OAuth2 client ID for GitHub.
          client_secret: XXXXXXXXXXX    # Specify the GitHub OAuth2 client secret.
          redirect_uri: https://localhost:8443/oauth2/github/callback # Specify the OAuth2 redirect URI for GitHub.
          scope: ['user:email']         # Specify the scope you want to get from GitHub's OAuth2. Usually, just reading the email is sufficient.
          signin_module:                # Specify the module name that implements the sign-in. see, cmdbox.app.signin.SignIn
          note:                         # Specify a description, such as a reference site for OAuth2 on GitHub.
          - https://docs.github.com/ja/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps#scopes
        azure:                          # OAuth2 settings for Azure AD.
          enabled: false                # Specify whether to enable OAuth2 for Azure AD.
          tenant_id: XXXXXXXXXXX        # Specify the tenant ID for Azure AD.
          client_id: XXXXXXXXXXX        # Specify the OAuth2 client ID for Azure AD.
          client_secret: XXXXXXXXXXX    # Specify the Azure AD OAuth2 client secret.
          redirect_uri: https://localhost:8443/oauth2/azure/callback # Specify the OAuth2 redirect URI for Azure AD.
          scope: ['openid', 'profile', 'email', 'https://graph.microsoft.com/mail.read']
          signin_module:                # Specify the module name that implements the sign-in. see, cmdbox.app.signin.SignIn
          note:                         # Specify a description, such as a reference site for Azure AD's OAuth2.
          - https://learn.microsoft.com/ja-jp/entra/identity-platform/v2-oauth2-auth-code-flow


- See also the contents of `.sample/sample_project/sample/extensions/user_list.yml`.