# Test environment runbook

There is no staging environment. The portal is tested against a separate **test OU** in your real Active Directory and a **dedicated application** in your real authentik. This runbook creates both, with the smallest possible rights. Nothing here touches existing users, groups or applications.

Time needed: about 45 minutes. You need domain-admin rights, access to authentik as an administrator, your reverse proxy (Zoraxy) and your mail provider's panel.

## What gets created

| Where | What |
| --- | --- |
| Active Directory | A test OU with six test users and two groups; a separate OU with a service account; delegated rights for that account on user objects in the test OU only |
| authentik | One OIDC provider and one application, restricted to a test group |
| Zoraxy | One host name that forwards to the portal container |
| Mail provider | One test mailbox for sending |

Reading is not restricted by this setup: in Active Directory, authenticated users can read most attributes of user objects by default, and so can the service account. The spine's wording that read rights are limited to a list is not enforced here (see the deferred-work note).

The service account may change `givenName`, `sn`, `displayName`, `mail`, `telephoneNumber`, `mobile`, and may use "Change Password", on **user objects inside the test OU**. It cannot create or delete anything, cannot reset passwords (unless you add `-AllowResetPassword`), and cannot write anywhere else.

## Step A: Active Directory

1. Copy `New-PortalTestEnvironment.ps1` to a domain controller (or a machine with the AD tools).
2. Pick the parent OU for the two new OUs. Run a dry run first and read the output:

   ```powershell
   .\New-PortalTestEnvironment.ps1 -ParentDn "OU=Organisation,DC=example,DC=local" -WhatIf
   ```

3. Run it for real (drop `-WhatIf`). The script prints **the passwords once**. Put them in your password manager now. It also prints the values to write down (see the values sheet below).
4. The six test users: `ptest-user1`, `ptest-user2` (for cross-user checks), `ptest-publisher`, `ptest-admin`, `ptest-disabled` (disabled account), `ptest-expired` (must change password at next logon). Their e-mail addresses use the example domain; change the address of one user to your test mailbox if you want to receive test e-mails.

## Step B: The certificate authority file

The portal checks the directory server's certificate against your internal CA, so the file must contain the **whole chain**: the root CA and any intermediate CA that signed the domain controller's certificate.

1. On the certificate authority server, export each CA certificate that is part of the chain (`certutil -ca.cert root.cer`, and the same for an intermediate if you have one), or export them from the "Certification Path" tab of the domain controller's LDAPS certificate.
2. Convert each to PEM (`certutil -encode root.cer root.pem`) and join them into one file `ca.pem` (the files can simply be put one after another).
3. Check it from the Linux host (replace the names):

   ```sh
   openssl s_client -connect dc1.example.local:636 -CAfile ca.pem -verify_return_error </dev/null | grep "Verify return code"
   ```

   It must say `Verify return code: 0 (ok)`.

Keep `ca.pem` on the Linux host. It is a public certificate, not a secret. Later the container mounts it.

## Step C: Prove the rights over LDAPS

From a machine that trusts your CA and can reach the directory server on port 636:

```powershell
.\Test-PortalLdaps.ps1 -Server dc1.example.local -BindUser svc-portal-test@example.local `
    -TestOuDn "OU=PortalTest,OU=Organisation,DC=example,DC=local" `
    -OutsideUserDn "CN=Some Person,OU=Elsewhere,DC=example,DC=local" -TestPasswordChange
```

Use the real server name and a real user outside the test OU for `-OutsideUserDn` (the check sends a request that changes nothing). `-TestPasswordChange` changes the password of `ptest-user1`; write the new one down. **Every line must say PASS.** If the password check fails with "access denied", tell the assistant: it then decides, before the password feature is built, whether the narrower right is enough or "Reset Password" is needed.

## Step D: authentik

Do not change any existing application. Labels may differ slightly between authentik versions.

1. Check, **without changing anything**, whether your existing LDAP source already covers the test OU (look at its base DN: a parent such as the whole domain or `OU=Organisation` covers it). If it does, wait for the next sync; the six test users, including the disabled and the expired one, will then appear in your production authentik and can be removed again at clean-up. If it does **not** cover the test OU, stop here and tell the assistant: the options are to widen the existing source (a change to existing configuration) or to add a second source just for the test OU (a new object only). After the sync, `ptest-user1` must have the same username in authentik as its AD logon name (the portal requires `preferred_username` to equal `sAMAccountName`).
2. Create a group `portal-test` and add `ptest-user1`, `ptest-user2`, `ptest-publisher`, `ptest-admin`, `ptest-disabled` and `ptest-expired` to it.
3. Create an **OAuth2/OpenID provider**: client type *confidential*; redirect URI (strict) `https://<portal-test-host>/auth/callback` (the sign-in ticket will use exactly this path; if it ever has to change, edit it here); scopes `openid`, `profile`, `email`; choose a signing key. Write down client ID and client secret.
4. Create an **application** for it and bind the group `portal-test` so only those users can use it.
5. Open the application's OpenID configuration page and write down the issuer address.

Please note what authentik does when you sign in as `ptest-disabled` and `ptest-expired` (it may refuse them). That answers an open question in the spec.

## Step E: Zoraxy

1. Add a host name for the test portal, for example `portal-test.<your domain>`, with a valid certificate, forwarding to `http://<docker host address>:8000`. The compose file currently publishes port 8000 on every interface of the host. Either bind it to `127.0.0.1:8000:8000` when Zoraxy runs on the same host, or firewall port 8000 so that only Zoraxy can reach it; the portal trusts proxy headers and must not be reachable directly.
2. Write down the address Zoraxy connects from as seen by the container. If Zoraxy and Docker run on the same host, that is usually the Docker network gateway, not the host's LAN address. The sign-in ticket (1.5) sets `TRUSTED_PROXIES` from it and checks it with a test request.

## Step F: Test mailbox

Create a mailbox at your provider for test mail. Write down the SMTP server name, port, security mode (usually STARTTLS or SSL), user name, password and the sender address.

## Values sheet (fill in; keep secrets out of this repository)

| Item | Value |
| --- | --- |
| Directory server (FQDN) | |
| Test OU (base DN) | |
| Service account (user name) | stored in password manager |
| Publisher group DN | |
| Admin group DN | |
| CA file location on the Linux host | |
| OIDC issuer address | |
| OIDC client ID | |
| OIDC client secret | stored in password manager |
| Portal test host name | |
| Zoraxy address as seen by the container | |
| SMTP server, port, mode | |
| SMTP user, sender address | |
| SMTP password | stored in password manager |

## Clean up when you are done

Delete the authentik application, provider and group; the Zoraxy host; the test mailbox; and the two OUs. The script created the OUs without deletion protection, so they can be removed in Active Directory Users and Computers with "Advanced Features" switched on. Remove the service account's OU last.

## When you are finished

Tell the assistant "1.2 is done". Ticket 1.2 stays open until you confirm that every check in Step C says PASS and that the authentik application lets `ptest-user1` sign in.