Sign-in protection

DartRelay's sign-in pages face whoever can reach them. This page explains the layers that slow down password guessing and keep unwanted visitors out: the failed-attempt lockout, the picture challenge (captcha), lists of allowed network addresses, and blocked addresses.

How the layers fit together

Each layer answers a different question. You can use any of them on their own, but they work best together.

The settings on these pages need the Security permission in the administrator's role. See Administrator roles and permissions.

The failed-attempt lockout

Every failed sign-in is counted against the network address it came from. When an address reaches the limit, DartRelay refuses further sign-in attempts from it for a set time, on every sign-in route: the portal, the console and the client application. The count covers wrong passwords and wrong one-time codes alike, so the second factor cannot be guessed either.

A successful sign-in from the address clears its count.

Setting the limits

1. Open System Settings. In the console, go to System → Settings.
2. Find the Login Rate Limiting section. It holds two fields side by side.
3. Set Max Failed Attempts. This is the number of failures an address may make before it is locked out.
4. Set Lockout Duration. This is how long the address stays locked out.
5. Click Save.

Who hears about a lockout

When an address is locked out, DartRelay sends the sign-in lockout message to everyone on the Admin Notification Emails list, naming the address. Messages are rate-limited so that a flood of attempts cannot flood your inbox. See Administrator notifications.

Behind a load balancer or reverse proxy

The lockout counts per network address, so DartRelay needs to see each visitor's real address. When DartRelay sits behind a load balancer or reverse proxy, every request arrives from the proxy's address unless DartRelay is told to believe the proxy's forwarded headers. Add the proxy's addresses to Trusted proxies on System → Load balancer; see Load balancer and ADC integration.

The picture challenge (captcha)

A captcha asks the visitor to prove they are a person before their password is even checked. It stops scripts from trying passwords at speed, and because the challenge is checked first, a refused challenge costs the server almost nothing.

The captcha settings are on Authentication → Security, in the captcha section.

Choosing a provider

Switching the captcha on

1. Open the Security page. Go to Authentication → Security and scroll to the captcha section.
2. Choose the provider. Leave Builtin selected unless you have keys for one of the others.
3. Tick the surfaces to protect. The admin console and the portal each have their own tick box (for example Require captcha on admin login) and their own threshold.
4. Set Show captcha after N failed attempts for each surface. 0 means the challenge is shown on every sign-in. A higher number shows it only after that many failures from the visitor's address.
5. For reCAPTCHA or Turnstile, paste the site key and secret key.
6. Click Save. For a third-party provider, DartRelay first contacts the provider to confirm the secret key is accepted. If the provider cannot be reached or rejects the secret, the save is refused and nothing changes.

Fields

Things worth knowing

• The same provider serves other challenges. The self-service password reset page and the human check for guest visitors use whichever provider you choose here. See Self-service password reset and Guest access without a sign-in.
• A third-party provider that cannot be reached blocks sign-in. If the server loses its route to Google or Cloudflare, sign-ins that need a challenge are refused rather than let through unchecked. See the recovery steps below.
• Leave domain checking on at the provider. DartRelay checks that the provider accepted the answer. Keep the provider's own setting that ties your keys to your domain switched on in its dashboard.
• Only the first sign-in form on a page gets a challenge. If a theme's sign-in page has two Sign-in blocks, the challenge is drawn on the first.
• The client application has no captcha. Sign-ins from the client application are protected by the failed-attempt lockout only.
• Refused challenges are written to the server log, not the audit log, because no account was reached.

If a captcha locks you out of the console

If a challenge cannot be shown or passed — for example a third-party provider is unreachable — you can switch the captcha off from the server itself. Add this setting to the server configuration file, dartrelay.config.json in DartRelay's data directory. Add it to what is already there rather than replacing the file:

{
  "DartRelay": {
    "Security": {
      "CaptchaDisabled": true
    }
  }
}

This setting always wins over what the Security page says. The Security page shows the exact path of the file and the same block, ready to copy. Remove the setting once the problem is fixed. See Server configuration file.

Allowed network addresses New in 2.0

If your users always connect from known networks — your offices, a VPN range, a partner's address — you can stop everyone else from seeing the portal or the console at all. Visitors from other addresses are refused before the sign-in page loads, with a page saying the portal is not available from their network.

The settings are on Authentication → Network Access, on the Allowed addresses tab. There are two independent switches, each with its own list:

Each list takes single addresses and address ranges. A list is kept when its switch is off, so you can switch a restriction off for a while without retyping it.

Restricting the console to your office

1. Open Network Access. Go to Authentication → Network Access. The Allowed addresses tab opens.
2. Tick Restrict Admin Portal Access to Specific IPs.
3. Enter your office addresses or ranges in its list.
4. Click Save. DartRelay checks your own request against the new list before saving. If the change would lock you out, the save is refused.

The console can always be opened from the DartRelay server's own desktop, whatever the lists say. The portal has no such exception.

Tenant addresses

Each address on Appearance → Tenancy & Branding can have a list of its own, set on that address's Access page under "Network access on this address". By default a visitor on that address must pass both the portal list (if switched on) and the tenant's list. Ticking the override makes only the tenant's list apply on that address. See Tenancy & Branding.

Rules the page enforces

• Entries that are not valid addresses or ranges, and loopback addresses, are refused.
• A switch cannot be ticked with an empty list.
• A switch cannot be turned on while requests arrive through a proxy DartRelay does not trust, because the addresses it would check are the proxy's, not your visitors'. Add the proxy to Trusted proxies first.

Example: a portal for clients, a console for staff

A company publishes its line-of-business application to three client firms. It ticks Restrict Admin Portal Access to Specific IPs and lists its own office range, so the console is invisible from the internet. It leaves the portal switch off, because clients connect from many places, and relies on the captcha and the lockout for the portal sign-in page instead.

Blocked addresses New in 2.0

A blocked address is turned away from the portal and the console with the message "This portal is not available from the network address you are connecting from." Use it for a scanner or crawler you have seen in the audit log, or an address that keeps failing sign-ins.

Blocking an address from the audit log

1. Open the audit log. Go to System → Audit Log.
2. Find a row from the address. The address column has a Block button.
3. Click Block. A prompt asks for a note, filled in with "Suspected IP". Change it if you like. Click Cancel to block nothing.
4. Confirm. You land on the Blocked addresses tab of Network Access, with the address listed, the time, your name and the note. The audit log row now shows Unblock.

The Block button is greyed out, with the reason shown when you hover over it, for addresses that must not be blocked: the server itself, an address already covered by a blocked range, a trusted proxy or load balancer, another server in your pool, your own address, or an address from which three or more different accounts have signed in over the last 14 days. That last one is probably an office gateway or shared connection, and blocking it would turn away everyone behind it. You can still type such an address into the add box if you are sure.

Blocking from the Network Access page

1. Open the Blocked tab. Go to Authentication → Network Access and choose Blocked addresses. The tab shows how many entries there are.
2. Type one or more addresses or ranges into the add box, with an optional note (up to 200 characters). The note is applied to every address added at the same time.
3. Add them. They appear in the Blocked everywhere table, newest first, with Blocked (UTC) and Note columns.

Below it, Blocked on one tenant address lists entries that apply to a single tenant address only. Those are added on the tenant address's Access page, under "Blocked on this address".

Each row has an Unblock button, and its note can be edited or cleared in place. Unblock removes exactly that entry. If a wider blocked range still covers the address, the page says so.

What cannot be blocked

The same rules apply everywhere an address is blocked. DartRelay refuses:

• an IPv4 range wider than /8, or an IPv6 range wider than /32;
• loopback addresses and any of the server's own addresses;
• a trusted proxy or load balancer, or a range overlapping one;
• another server in your pool;
• your own address.

Blocking, unblocking and note changes are recorded in the audit log.

What people see when their account has a problem

For Active Directory accounts, DartRelay tells people what is wrong only where the directory itself reported it, so the sign-in page never helps a stranger work out which accounts exist:

• Locked, disabled or expired accounts are named on the sign-in page.
• An expired password, or one that must be changed, takes the person to a change-password screen. See Expired passwords.
• A wrong password always gets the same general message. The reason for a failed console sign-in is written to System → Audit Log; read it there rather than on the page.

If something goes wrong

Everyone is locked out at once

DartRelay is probably behind a proxy it does not trust, so all visitors share one address. Check the address recorded for your own sign-in in the audit log, and add the proxy to Trusted proxies on System → Load balancer. A locked-out address is let in again once the lockout duration has passed.

The captcha settings will not save

For reCAPTCHA or Turnstile, the save is refused if the server cannot reach the provider or the provider rejects the secret key. Check the server's internet access and the keys. A threshold equal to or above Max Failed Attempts is also refused.

Nobody can sign in since a third-party captcha was switched on

The provider is probably unreachable from the server. Use the recovery setting in If a captcha locks you out of the console, then switch back to Builtin.

A visitor sees "Not available from your network"

Their address is not on an allowed list, or it is blocked. Check both tabs of Authentication → Network Access and, for a tenant address, that address's own Access page. The refusal page shows the address DartRelay saw, which is the one to add or unblock.

Locked out of the console by an address list

Open the console from the DartRelay server's own desktop, which is always allowed, and correct the list.

Related pages