Password policy and self-service reset

This page covers everything to do with passwords in DartRelay: making someone choose a new password, password expiry for portal accounts and directory accounts, what happens when a password has expired, and the "Forgot your password?" link that lets people reset their own.

Two kinds of password

Where a password lives decides who controls it:

• Portal accounts — accounts you create under Authentication → Users. Their passwords are kept by DartRelay, and DartRelay's own policy applies.
• Directory accounts — Active Directory accounts. Their passwords belong to the directory. DartRelay follows the directory's rules: it reads when a password expires and honours "User must change password at next logon", but it does not set the directory's policy.

The sections below say which kind each feature applies to.

People changing their own password

Anyone signed in to the portal can change their password from the profile page, where the Password card is the first thing on the page. A portal account's password is changed in DartRelay; a directory account's password is changed in the directory, so the new password works everywhere that account is used.

Making someone choose a new password

Portal accounts

Every portal account has a "must change password" flag. When it is set, the person is taken to a change-password screen at their next sign-in and cannot continue until they choose a new password. Changing the password clears the flag.

The flag is switched on automatically when an administrator creates an account or sets someone's password on Authentication → Users. That way the password you handed over is used only once.

1. Open the user. Go to Authentication → Users and edit the account.
2. Set a new password if you are resetting one. The must-change flag is switched on for you.
3. Save. Give the person the temporary password. At their next sign-in they choose their own.

When one administrator sets another account's password, DartRelay sends the "password set by an administrator" message to the Admin Notification Emails list. See Administrator notifications.

Directory accounts

Tick User must change password at next logon on the account in Active Directory. When the person next signs in to the portal, DartRelay takes them to the change-password screen and the new password is set in the directory.

Expired passwords and the change screen

When a directory account's password has expired, or must be changed, the person is not simply told their password is wrong. They are taken to a change-password screen that carries your theme — the same logo, background and colours as the sign-in page.

1. They type their current password again, and the new one twice.
2. The screen is open for ten minutes. After that they start again from the sign-in page.
3. When the change succeeds they are sent back to sign in normally with the new password. Two-factor authentication, agreements and every other sign-in check then run as usual.

This applies to the portal sign-in page. The console does not offer it.

To switch the expired-password screen off, add this to the server configuration file, dartrelay.config.json, alongside what is already there:

{
  "DartRelay": {
    "Auth": {
      "PortalPasswordChangeOnExpiry": false
    }
  }
}

See Server configuration file.

Password expiry

Portal accounts

You can give portal account passwords a maximum age in days. When a password is older than that, the person is taken to the change-password screen at their next sign-in.

1. Open the Security page. Go to Authentication → Security and find the password policy.
2. Enter the maximum password age in days. 0 means passwords never expire, which is the default.
3. Save.

To exempt a single account — a shared kiosk account, for example — open it under Authentication → Users and mark its password as never expiring.

Directory accounts

For Active Directory accounts the expiry date comes from the directory, including "password never expires". DartRelay has no setting of its own for them.

Showing people when their password expires

Add the Password expiry block to the portal's home page or footer in the theme builder. It shows a line such as "Password expires in 3 days", "today" or "tomorrow", or "No expiration" when there is none. When DartRelay cannot find out — a directory that cannot be reached, for example — it shows nothing rather than guessing. See Building the sign-in and home pages.

Self-service password reset

With self-service reset switched on, the sign-in page shows a "Forgot your password?" link. The person enters their username or email address, receives an email with a link, and chooses a new password. It saves your help desk a call, and it works for portal accounts and directory accounts.

Who can use it

• Portal accounts that are active and have an email address. Administrator accounts and the guest account are never eligible.
• Directory accounts that are enabled, are allowed to change their own password, and are not members of the directory's protected administrator groups (such as Domain Admins).

Eligibility is checked when the link is requested, when the reset page opens and when the password is set. Someone who is not eligible sees exactly the same message as someone who is, so the page never reveals which accounts exist.

Before you begin

• Set up email delivery and send yourself a test. See Email delivery and templates.
• For directory accounts, give the account the DartRelay service runs as the Reset password right on the organisational units that hold your users, and Write lockoutTime if you want resets to unlock locked accounts. Use the Delegation of Control wizard in Active Directory Users and Computers. Without these rights the person sees that the password "could not be changed just now", and the server log names the missing right.
• Make sure people cannot edit their own email address in the directory. The reset link goes to that address.

Switching it on

1. Open the Security page. Go to Authentication → Security and find the Password Reset card.
2. Switch password reset on. This is the master switch, and it is off by default.
3. Choose how people identify themselves (see the table below).
4. Set the link address — the portal address that reset links should point to, for example https://portal.example.com.
5. For directory accounts, choose the attribute that holds the email address. The default is mail. You might use userPrincipalName if your UPNs are email addresses.
6. Save the card.
7. Show the link on the sign-in page. Go to Appearance → Portal Themes, edit the theme's sign-in page, open the Sign-in block's settings and switch on the "Forgot your password?" link. You can change its text there. Save the theme.

The link appears only when both the master switch and the theme's link are on. A theme on its own cannot open password reset.

Settings

What the person sees

1. They click "Forgot your password?" on the sign-in page and enter their username or email address (or both, depending on your setting), and answer the challenge if it is on.
2. The page shows the same sentence whatever happened, so nobody can use it to find out which accounts exist.
3. If the account is eligible, an email with a link arrives at the address stored on the account — never at an address typed into the form.
4. The link opens a reset form on your themed sign-in page. They choose a new password, and are returned to the sign-in page with a "password changed" notice.
5. A confirmation email then goes to the same address, saying when and from which network address the password was changed, and asking the owner to contact IT if it was not them.

How the links are protected

• A link works once. It also stops working if the password is changed any other way, or if an administrator changes the account's email address.
• Requests are limited per network address, one email per account every two minutes, and a limited number of attempts per link.
• Reset requests and results for real accounts are recorded in the audit log. Names that match no account are not recorded, because anyone can type them.

The two emails

Both messages are templates under Email → Templates: Password reset link (which must contain the {link} shortcode) and Password reset confirmation. You can reword and translate them. Switching the confirmation off does not stop resets working. See Email templates.

Example

A company's users sign in with Active Directory accounts whose mail attribute holds their work address. The administrator delegates Reset password and Write lockoutTime on the Staff organisational unit to the DartRelay service account, switches password reset on with "Username or email", leaves the captcha and unlock on, enters https://apps.example.com as the link address, and switches on the link in the theme. A user locked out after a holiday clicks the link, receives the email, sets a new password and is unlocked in one step.

If something goes wrong

The "Forgot your password?" link does not appear

Both switches must be on: the master switch on the Password Reset card, and the link in the Sign-in block of the theme the sign-in page is using. If the address people use has its own theme under Tenancy & Branding, switch the link on in that theme too.

Nobody receives a reset email

Check, in order: email delivery works (send a test from a template); the account is eligible and has an email address; the link address is set. When no trusted link address is available, nothing is sent and the Password Reset card shows a warning. The audit log records why a reset email for a real account was not sent.

The reset fails with "could not be changed just now"

For directory accounts, the DartRelay service account lacks the Reset password right on the user's organisational unit. The server log names the missing right.

The link says it has expired or was already used

Each link works once and only for the link lifetime. The person should request a new one.

A new portal user cannot get past the change-password screen

They must type the temporary password you gave them as the current password. If the screen was open longer than ten minutes, they need to sign in again first.

Related pages