Password delivery
Choose how a password-reset link reaches a user — handed over by an administrator, sent by your own mail server, or sent through EmailJS.
- Version: 0.4
- Role: superadmin
- Type: task
A CID222 password reset is always the same object: a one-time link with a limited life. Settings → Password delivery decides how that link reaches the person who needs it — an administrator copies it out of the dashboard, your own mail server sends it, or a hosted EmailJS template does.
What do I need?
- Licence
- Any
- Role
superadmin
Prerequisites
- You sign in as superadmin. This is one of the few panes the API restricts to superadmin rather than admin_user.
- For the mail-server path: the address and port of an SMTP relay the appliance can reach, and a from-address it will accept.
- For a privately signed relay: its issuing CA certificate as PEM.
- For EmailJS: an EmailJS service, public key and reset template, configured on the appliance as environment values, and outbound internet access.
- A dashboard address users can reach, if the appliance is published under a different name than the one requests arrive on.
/assets/screenshots/settings-password-delivery@0.4.pngThe three channels
| Channel | The page calls it | What happens on a reset |
|---|---|---|
admin_link | Administrator hands out the link (no mail) | Nothing is sent. An administrator generates the link on the user's record and hands it over. Self-service Forgot password is answered with a message telling the user to ask an administrator, and no token is minted. |
smtp | Your own mail server (SMTP) | The appliance composes the mail itself and sends it through your relay. |
emailjs | EmailJS (hosted, needs outbound internet) | The appliance calls EmailJS, which renders your template. The mail body is yours, not CID222's. |
Until someone chooses, the environment decides: EmailJS if it is configured, otherwise the administrator link. The page says so — Nothing has been chosen yet, so the environment is deciding. Saving makes the choice explicit.
The link itself is the same in every case: a 64-character single-use token, valid for
PASSWORD_RESET_EXPIRES_MINUTES minutes — 60 by default. Only its hash is stored, using it clears
it, and issuing a new link invalidates the previous one.
Warning
Directory-backed accounts cannot be reset here at all. The appliance refuses with This account is managed by your directory (AD/LDAP). Its password must be reset in the directory — a link issued here would set a password sign-in never checks. Point those users at Directory self-service page instead.
Hand the link over yourself
This is the default, and it is the only channel that needs no infrastructure.
Select the channel
Select Settings → Password delivery, set Delivery channel to Administrator hands out the link (no mail), and select Save.
A toast reports Password delivery settings saved.
Generate a link for a user
Open Tenants, find the account, and select Reset password.
The dialog shows a one-time link with a copy button and states Expires …. Generating a new link invalidates any previous one.
Deliver it out of band
Copy the link and give it to the user over a channel you trust.
The dialog is explicit about why that matters: No email is sent, so deliver it securely: anyone with the link can set the password until it expires or is used.
Send through your own mail server
An air-gapped appliance is not necessarily a mailless one — most closed networks run an internal relay, and pointing the appliance at it restores self-service reset.
Select the channel
Set Delivery channel to Your own mail server (SMTP).
A Mail server card appears.
Enter the relay address
Set Host and Port — for example mail.example.corp and 587.
Both are required, along with a from-address, before the channel can deliver.
Choose the encryption
Set Encryption to STARTTLS (required), TLS on connect or None.
STARTTLS is enforced, not attempted: a server that does not offer it fails the connection rather than continuing in the clear.
Authenticate, or do not
Fill Username and Password, or leave Username blank.
A blank username sends no credentials at all, which is what an internal relay accepting mail from the LAN expects.
Set the envelope
Set From address, and optionally From name and Reply-to (optional).
These appear on the mail the user receives.
Handle a privately signed relay
If your relay presents a certificate from an internal CA, paste that CA into CA certificate (optional).
Verification then succeeds without weakening it. Do not verify the certificate is the last resort: the connection stays encrypted, but nothing proves who is on the other end.
Test and save
Select Test connection, then Save.
A successful test reports Connected to the mail server. It connects, negotiates TLS and authenticates — it sends no mail.
Point reset links at the right address
Set the dashboard address
Under Links, set Dashboard address to the URL your users open, for example
https://cid.example.corp.
Left blank, the appliance uses the address each request arrives on, which is usually right on an appliance and wrong behind a rewriting proxy.
Redirect directory users
Set Directory self-service page to your own password-reset portal.
Directory-backed accounts hold no password on the appliance, so this is the only useful destination for them.
What the user receives
On the SMTP channel the appliance composes the mail itself, in English or Turkish according to Mail language. The English mail has the subject Reset your password and reads:
Hello name,
Use the link below to set a new password.
The link can be used once and expires in 60 minutes.
If you did not request this, you can ignore this message — your password stays unchanged.
The action is a button labelled Set a new password, with the raw link repeated underneath so a mail client that strips links still leaves something to copy. There is no template editor.
On the EmailJS channel the body is entirely your own template. It must use the parameters
to_email, username and reset_link.
Fields reference
| Field on the page | Stored as | Default | Notes |
|---|---|---|---|
| Delivery channel | channel | unset | admin_link, smtp or emailjs. Unset means the environment decides. |
| Mail language | locale | en | en or tr. Applies to the mail CID222 composes, not to an EmailJS template. |
| Host | smtp_host | — | Required for SMTP. |
| Port | smtp_port | — | Required for SMTP, 1–65535. |
| Encryption | smtp_security | starttls | none, starttls or tls. |
| Username | smtp_username | — | Blank sends no credentials. |
| Password | encrypted column | — | Never returned. Blank on save keeps the stored value; an empty string clears it. |
| From address | from_address | — | Required for SMTP. |
| From name | from_name | — | |
| Reply-to (optional) | reply_to | — | |
| CA certificate (optional) | tls_ca_certificate | — | PEM, up to 16 KB. |
| Do not verify the certificate | tls_reject_unauthorized_disabled | off | |
| Dashboard address | reset_url_base | — | Falls back to PASSWORD_RESET_URL_BASE, then the request origin. |
| Directory self-service page | directory_reset_url | — |
EmailJS is configured only as appliance environment values — EMAILJS_SERVICE_ID,
EMAILJS_PUBLIC_KEY, EMAILJS_RESET_TEMPLATE_ID, and optionally EMAILJS_PRIVATE_KEY. Nothing
about EmailJS is stored in the database or editable on this page.
The stored SMTP password is encrypted with a key derived from JWT_SECRET. Rotating that secret
makes it undecryptable and you must retype it.
Verify
- Select Test connection. It reports Connected to the mail server, and the line under the buttons reads Last test timestamp: connected.
- Issue a reset for a test account and confirm the mail arrives with the subject Reset your password and a working link.
- Open Event logs. The reset writes
PASSWORD_RESET_LINK_ISSUED, thenPASSWORD_RESET_DELIVERYrecording the channel and whether delivery succeeded, andPASSWORD_RESET_COMPLETEDonce the user sets the new password. None of the three records the token or the link. - Follow the link, set a password, then follow the same link again. It is refused with Invalid or expired password reset token.
If it fails
The test result is the transport's own words, stored in Last test and shown on the page.
- 502 5.5.1 Command not implemented → you chose STARTTLS and the server is plaintext-only. There is no silent downgrade. Use None on a trusted segment, or fix the relay.
- self-signed certificate → the relay's certificate is privately signed and you pasted no CA. Paste it into CA certificate (optional).
- Hostname/IP does not match certificate's altnames → you connected by IP with TLS on. Use the name on the certificate.
- Greeting never received → you chose None against a server that speaks TLS immediately. Use TLS on connect.
- channel_not_usable: smtp_host, from_address (or any subset) → those fields are empty. The page also says so above the form: This channel cannot deliver yet — missing: ….
- admin_link_channel → Test connection was run on the administrator-link channel, which sends nothing. The button is disabled for that channel.
- A test on EmailJS reports success without contacting anything → that is the design. EmailJS has no connectivity probe short of sending, so being configured is all the test can honestly assert.
- The user reports the link goes to the wrong host → set Dashboard address.
- The reset is refused for one user with the directory message → that account is directory-backed. Reset it in the directory.
- Repeated Forgot password attempts return Too many requests, please try again later. → the rate limiter. Wait, or hand out an administrator link.
Note
Self-service Forgot password always answers If an account with that email exists, a password reset link has been sent. — whether or not the account exists, and whether or not delivery worked. That is deliberate, so the page cannot be used to enumerate accounts. Check Event logs for what actually happened.
Next steps
- Tenants and users — where an administrator generates a link for one account.
- Active Directory and LDAP — for accounts whose passwords never live on this appliance.
- Settings — the other panes, and which role reaches them.
Last updated on