Login Configuration

The login process is configurable based on the needs of an organization. An administrator can configure the login to display security challenge questions, terms and conditions of use, messages at login, and the frequency that those messages are displayed.

To make changes to the login process, SSH into your appliance and locate the file opt/search/appliance5/conf/login.json. You can also access the login.json file by going to Configuration once you have opened the Admin tile.

The following services need to be restarted after the changes have been made to this file; professional services can help with this if needed:

• ps-admin-portal

• ps-search-ui

• ps-searchserver-ui

• ps-feeder-ui

• ps-web-server (optional)

login.json

Below is a copy of the login.json file with explanations for each line of code. These items are in key:value pairs. We suggest that items are left in this order as you are configuring your own file. That being said, not all elements of the file are needed. Feel free to exclude elements that are unnecessary or undesired.

{
    "cookie-secret": "SecretForSecurity", // This should be randomly generated
    "cookie-timeout": 120, // Time is displayed in seconds; if user does not move on to next screen, the user is reverted to the enter username and password screen
    "security-questions": [ // Specify all of the security questions of your choice for the users
        "What is the name of your favorite stuffed animal?",
        "What is your favorite board game?",
        "Who was your best friend in fourth grade?",
        "What was your favorite vacation?",
        "Where do you hide your house key?"
    ],
    "locked-user-message": "Your account is currently locked or disabled. Please contact an administrator in order to get your account unlocked or re-enabled.", 
        // This allows the administrator to customize a message when the user has been locked.
    "login-notice-file": "/etc/issue.net",
    "login-notice": "My Login Message",
    "help-text": { // Help text describing some functionality to the user.
        "password-policy": "<p>The password must meet the following criteria:<ul><li>Contains a minimum of twelve characters</li> <li>Cannot be one of your 24 most recent passwords</li></ul></p>",
        "duo-2fa-push": "This is the html displayed on the push notification/phone call page while waiting for the user to accept the 2FA from Duo. If you include '{method}', it is replaced with either 'phone call' or 'push notification'.",
        "duo-2fa-sms": "Please enter the sms text code received from Duo.",
        "duo-2fa-mobile_otp": "Please enter your one-time passcode from the DuoMobile application.",
        "duo-enroll-note": "This is a note to show users on the enrollment page. By default it says, 'You will not be able to log in until after enrolling in Duo Two Factor Authentication.'.",
        "duo-enroll-instructions": "These are the instructions on how to enroll in Duo 2FA. It MUST include '{enrollURL}' since that should be replaced with the Duo enrollment URL for the user. The default is, 'If you have the DuoMobile application, scan the QR code to quickly enroll in Duo 2FA. If you cannot scan the QR code, you can add a new \"Duo Security\" account by using the activation code. Alternatively, visit <a href='{enrollURL}' target='_blank'>this page</a> to enroll in Duo without the DuoMobile application.'."
    },
    "messages": [{ // Messages to be displayed on the login screen
        "type": "primary",
        "message": "Welcome to the system!"
    }],
    "system-messages": [{ // Messages to be displayed after the user has logged in.
        "type": "warn",
        "message": "Server going down for updates tomorrow at noon."
    }],
    "login-challenges": [ // A list of authentication challenges that must be completed
        { // Each challenge must have a key which is the name of the challenge plugin.
          // Only one challenge may be specified at a time.
          // Certain challenges may be used multiple times.
          // The value for the main challenge key is the configuration for that challenge
            "Agreement": {// An agreement may have a header text (optional), a message block or a file (message takes precedence), 
                         // and a prompt-interval block to specify how many days until the agreement appears again.
                         // Not all items are required.
                "header": "Acceptable Use Policy",
                "message": "By clicking accept, you agree...",
                "file": "/etc/issue.net"
            },
            "cookie": "aup1"// A "cookie" key must be specified for all agreement blocks if more than one is specified.
        },{ // Minimal secondary agreement block
            "Agreement": {
                "message": "No header means that it gets set to 'Acceptable Use Policy'"
            },
            "cookie": "AUP" // A "cookie" key must be specified for all agreement blocks if more than one is specified.
                            // It must be unique and cannot be named the same as any keys that may go into "login-challenges".
        },{
            "QuestionAnswer": { // This must be used if "security-questions" is included in the file and prompts the user to enter any unanswered questions
                "question-mode": "user-choice", // See below for more valid options, explanations, and warnings. 
                "limit": 3  // This can be any number from 1 to how ever many questions you have
        }},{
            "Agreement": {
                "header": "End-User License Agreement",
                "message": "This shows once per 30 days",
                "prompt-interval": 30 // Asks every 30 days upon first login after the interval is set.
            },
            "cookie": "eula"
        },{
            "Agreement": {
                "header": "This Agreement uses a crontab style string to set when user's will need to agree to it again.",
                "message": "We also set the cookie for the agreement so that we can have multiple agreement blocks",
                "reattest-time": "0 12 15 1 *" // Users will have to agree at noon on January 15 every year; see https://en.wikipedia.org/wiki/Cron#CRON_expression for more cron strings
            },
            "cookie": "CRON"
        },{ // The Question challenge asks a random security question
            "Question": {}
        },{ // TemporaryPassword prompts the user to reset their password if it has expired or was reset by an administrator.
            "TemporaryPassword": {}
        },{ // SystemMessages displays any messages that are specified in the config system-messages if the password is about to expire.
            "SystemMessages": {
                "reattest-time": "0 12 1 1 *"
            }
        },{
            "Duo2fa": {
                "api_hostname": "Your Duo Auth API hostname",
                "integration_key": "Your Duo Auth API integration key",
                "secret_key": "Your Duo Auth API secret key",
                "allowed_methods": ["push", "sms", "phone", "mobile_otp"],
                "preferred_method": "push"
            },
            "cookie": "Duokie"
        }
    ]
}

Configuration Guidelines

• Using "cookie-secret": "SecretForSecurity" is required, everything else is optional.

• Using "QuestionAnswer" is required if "security-questions" is used.

• Items that are intended as a number, must be entered as a number: enter 30 not "30" for prompt-intervals.

• If keys are spelled incorrectly, an error occurs. String values do not go through the same checking process and may contain spelling errors if the user does not proofread carefully.

• Choosing to not require an element can either mean deleting it altogether or leaving the key blank: "security-questions": [].

• A non-secure message, "message", is shown on the same screen where the user enters his or her username and password. Anyone with access to the login screen can see these messages.

• A system message is shown only after a user has successfully entered a username and password and has successfully answered the required number of challenge questions. These message are displayed only to authorized users and can contain more sensitive information.

• If more than one message is needed, enter the block as below:
  

  "messages": [{
          "type": "primary",
          "message": "Welcome to the system!"
  },{
          "type": "primary",
          "message": "The person with the best Halloween costume wins $100. Start planning now."
  }],

• A "cookie" key must be specified for all agreement blocks if more than one is specified. It must be unique and cannot be named the same as any keys that may go into "login-challenges".

• The different type:s of messages are below:

  • warn: red background

  • primary: blue background.

  We recommend using primary for the majority of the messages in order to make the warnings more noticeable when they occur.

• It may be easier to change the name of the cookie rather than completing a new message block if the message remains the same, but you need the user to see the message again next time they log in.

QuestionAnswer

Below are the available options for the "question-mode" parameter:

• "default"
  The user is required to answer all of the security-questions in the login.json. All questions are displayed at the same time for the user to answer.
  

  WARNING: There cannot be a limit configured if this is the question-mode. If a limit is specified in the login.json, then the middleware services will not start.

  "QuestionAnswer": {
      "question-mode": "default"
  }
  

• "one-by-one"
  The user is required to answer all of the security-questions in the login.json. The questions are displayed one at a time. After the user submits the answer to one question, they are prompted to answer the next until they have answered all of the questions.
  

  WARNING: There cannot be a limit configured if this is the question-mode. If a limit is specified in the login.json, then the middleware services will not start.

  "QuestionAnswer": { 
      "question-mode": "one-by-one" 
  }
  

• "limited"
  The user only has to answer a limited number of the security-questions in the login.json. There will be a number of dropdown boxes equal to the configured limit. The user must select a question from each of the dropdowns and then answer the question they selected.
  

  WARNING: There must be a limit configured in the login.json if this is the question-mode. If a limit is not specified in the login.json, then the middleware services will not start.

  "QuestionAnswer": { 
      "question-mode": "limited", 
      "limit": 3
  }
  

• "user-choice"
  

  This is the exact same as limited.

The limit parameter allows users to specify 100 security-questions in the login.json, but only require their users to answer 5 (or any desired number).