DMC-2026 PERMISSION SCOPING PROBE
=================================

WHAT THIS IS
------------
A small diagnostic program that answers one question about your Content Server
test estate:

    When Content Server is asked for a folder listing using a ticket obtained by
    impersonating a user, does it return what THAT USER is allowed to see?

That is all it does. It does not test anything else, and it produces a single
plain-text report that you send back to us.

We need the answer because the new DMC browse page will fetch listings on behalf
of the person using it. If Content Server scopes those listings to the user, the
page shows each person their own view. If it does not, everyone would see the
service account's view instead. That difference has to be established on a real
estate before the code is written to depend on it.


WHAT IT DOES TO YOUR SYSTEM
---------------------------
Nothing. To be specific:

  * It creates nothing, changes nothing and deletes nothing.
  * It does not connect to any database.
  * It asks OTDS two questions before anything else: whether the account you name
    is allowed to impersonate, and which of your OTDS resources is Content Server.
  * It then signs in to Content Server once as that account, to establish that the
    mechanism works before either test user is involved.
  * It reads ONE folder listing, twice - once as each of two test users.

It is read-only in the strict sense: every request it makes is a login or a read.

HOW IT SIGNS IN, since that is the first thing worth asking about:

It authenticates ONCE, with the account you name on the command line, using the
password you type in. It then asks OTDS for a ticket for each test user BY NAME -
OTDS calls this impersonation - and presents that ticket to Content Server, which
issues an ordinary session ticket for that user. The probe never authenticates as
the test users and never sees their credentials.

It is worth being exact about which mechanism that is. This is the OTDS route:

    POST {your OTDS}/otdsws/rest/authentication/ticketforuser

It is NOT the route the DMC you run today uses. That one impersonates through
Content Server Web Services, inside the DMC service. The two achieve the same
thing by different means, and the reason this probe exists is that the OTDS route
has not been demonstrated on your estate.

That is why you do not need the test users' passwords, and why you should not send
them to us. If the account cannot impersonate, the probe stops before it touches a
test user and names which prerequisite is missing.

The tickets it obtains expire on their own - the Content Server ones within the
hour. Nothing needs revoking afterwards; there is nothing to revoke.


WHAT YOU NEED BEFORE RUNNING IT
-------------------------------
1. AN ACCOUNT THAT OTDS WILL LET IMPERSONATE. That means an existing OTDS
   ADMINISTRATOR - a member of your OTDS administrators group, normally
   otadmins@otds.admin. One of your own administrator accounts will do.

   You do NOT need to create a service account for this. The probe needs no
   Content Server account of its own, no database access, and no new credential
   anywhere.

   The account must be an OTDS administrator (or a registered OTDS resource).
   Content Server System Administration rights do not count for this: OTDS
   refuses a Content Server administrator who is not also an OTDS one.

   You do NOT need to change "Allow impersonation" on the Content Server
   resource in OTDS. We tested it both ways: an OTDS administrator impersonates
   with it off, and ticking it does not let anyone else. The probe reads it and
   records it in the report, and carries on whichever way it is set.

   The probe checks the account before it touches a test user, and says so
   rather than failing later.

   You will be asked for the account's password when the program starts. The
   password is typed in, not passed on the command line, and it is not written
   to the report or to any log.

   (The command-line switch is still called --ServiceAccount. That is the name
   of the argument, not a requirement for a dedicated account.)

2. TWO ORDINARY TEST USERS. Neither may hold System Administration Rights - an
   administrator can see everything regardless of permissions, so the comparison
   would prove nothing. The program checks this and stops if either user is an
   administrator. You do NOT need their passwords: they are reached by an
   impersonation ticket, as described above.

   TWO MORE OF THE EIGHT PRIVILEGE BOXES are worth clearing if you can: Content
   Manager rights and Grant Discovery rights. We do not know whether either lets
   a user see items their permissions would otherwise hide, and while that is
   unknown the probe will not report "the two users saw the same thing" as a
   finding about a user who holds one. The run still happens, and a DIFFERENCE
   between the two listings is still reported as proof - it is only the negative
   result that gets withheld, because that is the one the privilege could explain.

   ONE THING CAN STOP THE RUN THAT IS NOT YOUR FAULT AND IS WORTH KNOWING IN
   ADVANCE. Content Server shows a user's privileges to administrators only. The
   probe therefore reads them through the account from point 1, which it can only
   do if that account is a Content Server administrator as well as an OTDS one. If
   it is not, and Content Server declines to tell an ordinary user their own
   privileges, the probe stops rather than assume. Running again with an account
   that is both is usually the quickest way past it, and the report says so.

3. A FOLDER that both test users can open.

4. ONE ITEM INSIDE THAT FOLDER that the FIRST user can see and the SECOND cannot.
   This is the heart of the test. Set the permission however you normally would.

   THEN VERIFY IT BY HAND, BEFORE RUNNING THE PROBE. Log in to Content Server as
   the second user, open the folder, and confirm the item is genuinely not there.

   This is worth the two minutes. On our own estate we removed Public access from
   an item and assumed that was enough - a group grant was still in place, the
   second user could still see it, and the run reported no difference. The probe
   cannot tell "the permission was not what you thought" apart from "Content
   Server ignores the ticket", so it will report the ambiguity rather than guess,
   and the cycle is wasted. Confirming it in the interface first removes the
   ambiguity before it can cost anything.

   PUBLIC ACCESS IS THE SAME TRAP WEARING A DIFFERENT HAT. Nearly every user holds
   the Public Access privilege, which lets them reach any item whose permissions
   have Public Access switched on. An item can therefore look restricted in its
   named permissions and still be visible to the second user through that one.
   Check it explicitly while you are in there; it is the commonest way a fixture
   that reads as correct turns out not to be.

5. NETWORK ACCESS from the machine you run it on to both OTDS and Content Server.

   BOTH http:// AND https:// ADDRESSES WORK. Give the URLs exactly as you would
   type them into a browser. The OTDS address must be the SERVER ROOT - host and
   port, nothing after it - because the probe appends the OTDS service path
   itself. Anything you put after the port is discarded.

   HTTPS uses this machine's normal certificate trust: if the certificate is
   trusted here, the probe connects; if it is not - a self-signed or internal-CA
   certificate on a machine that does not have the CA installed - the probe
   reports that it could not connect and stops. There is no option to skip
   certificate checking, deliberately. Run it from a machine that already trusts
   the certificate, which is usually any machine your administrators browse
   Content Server from.

6. THE NAME OF YOUR OTDS PARTITION, if OTDS has more than one - and it almost
   always does. OTDS identifies people as name@partition, and on a Content
   Server estate the partition is usually called "Content Server Members". You
   will find the list in the OTDS administration pages under Partitions.

   Pass it as --Partition. The probe will try the bare login name as well, but
   that is a guess: on every estate we have tested, the partition-qualified form
   is the one that works. Treat it as required unless you know OTDS has only one
   partition.

Points 1 to 4 and 6 are things only you can set up or look up, which is why they
are inputs rather than assumptions.


HOW TO RUN IT
-------------
Open a COMMAND PROMPT in this folder and run the program with your own values:

  Dmc.Gateway.PermissionScopingProbe.exe ^
    --OtdsUrl=https://otds.yourcompany.local:8443 ^
    --OtcsUrl=https://cs.yourcompany.local/OTCS/cs.exe/api/ ^
    --ServiceAccount=svc_dmc ^
    --Partition="Content Server Members" ^
    --UserA=testuser1 ^
    --UserB=testuser2 ^
    --FolderId=12345 ^
    --ChildId=12346

  --OtdsUrl          your OTDS server root, as you would type it into a browser
  --OtcsUrl          the Content Server REST API address, ending in /api/
  --ServiceAccount   the account from point 1
  --Partition        the OTDS partition from point 6
  --UserA            the test user who CAN see the item
  --UserB            the test user who CANNOT see it
  --FolderId         the folder from point 3
  --ChildId          the item from point 4

TWO THINGS ABOUT THE COMMAND ITSELF, both of which cost an afternoon if missed:

  * USE DOUBLE QUOTES around any value containing a space, as shown above for
    --Partition. A command prompt does not treat 'single quotes' as grouping: it
    would hand the program --Partition=Content and throw the rest away, and the
    run would fail later with a confusing message about impersonation. Double
    quotes group correctly.

  * THE ^ AT THE END OF EACH LINE is the command prompt's line continuation. If
    you are using PowerShell instead, replace each ^ with a backtick ` or put
    the whole command on one line.

Optional:

  --EstateName=acme-test                 a label used in the report filename
  --OutDir=C:\Temp                       where to write the report

It will then ask for the service account password. Type it and press Enter;
nothing is echoed to the screen while you type.

It takes a few seconds - under a minute in all but the slowest cases. There is no
progress bar because there is nothing long-running to report on.


WHAT IT PRODUCES
----------------
One plain text file in the current folder (or the folder given by --OutDir),
named like:

    permission-scoping_acme-test_20260817-153058.txt

Please send that file to:

    >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
    >>>  SEND THE REPORT TO:                                          <<<
    >>>                                                               <<<
    >>>      Name:   Ian Morrison                                     <<<
    >>>      Email:  imorrison@blubaker.com                           <<<
    >>>                                                               <<<
    >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>

Use this subject line, so it lands where we are watching for it:

    Permission scoping probe - <your estate name>

IF IT DOES NOT ARRIVE, suspect a mail gateway before you suspect us: some strip
.txt attachments without telling either end. The report is plain text and nothing
in it needs to be a file - open it, copy the whole thing, and paste it into the
body of the message instead.

The report says the same address in its own last lines, so it still knows where it
is going if it gets separated from these instructions.

You are welcome to read it first; it is written to be read. It contains:

  * what it connected to and what it was told to test
  * each request it made and the response status
  * the checks it ran on your fixture before drawing any conclusion
  * the two listings, by node id
  * a verdict

The report contains NO passwords and NO session tickets. Every line is checked
before it is written, and anything that looks like a credential is replaced with
<REDACTED>. It does contain the node ids and names in the one folder you nominate,
so choose a test folder rather than something commercially sensitive.


THE VERDICT
-----------
One of three:

  PROVEN            The item appeared for the first user and not the second.
                    Content Server scopes the listing to the impersonated user.

  DISPROVED         Both users saw exactly the same rows. Either Content Server
                    is not scoping the listing, or the second user can in fact see
                    the item. The report says how to tell which.

  CANNOT CONCLUDE   The test could not be run properly. This is NOT a finding that
                    anything is broken. The report names exactly what stopped it
                    and what to change.

                    Before it reaches your test users at all:
                      - the account from point 1 is not an OTDS administrator
                      - OTDS lists no Content Server resource, or more than one,
                        so --ResourceId is needed to say which one is meant

                    Once it has them:
                      - Content Server is in administration mode (it then admits
                        administrators only, so the test users cannot be
                        impersonated at all)
                      - one of the test users is a system administrator
                      - Content Server would not say whether a test user is an
                        administrator, which it tells administrators only - see
                        point 2
                      - a test user holds Content Manager or Grant Discovery
                        rights AND the two listings came back identical, so the
                        privilege may be the reason rather than the ticket
                      - the nominated item is not visible to the first user, or is
                        not in the nominated folder

If you get CANNOT CONCLUDE, the report tells you what to adjust. Adjusting it and
running again is expected and costs nothing.

For automated use the exit code is 0 for PROVEN, 1 for DISPROVED, 2 for CANNOT
CONCLUDE and 3 for a mistake in the command line.


AFTERWARDS
----------
1. COPY THE REPORT SOMEWHERE SAFE FIRST. By default it is written into this same
   folder, so deleting the folder deletes the report with it. (If you passed
   --OutDir it is already elsewhere, but copy it anyway rather than checking.)

2. THEN DELETE THIS WHOLE FOLDER. There is nothing to uninstall: no service, no
   scheduled task, no registry entry, and nothing left behind on Content Server or
   OTDS.

If anything is unclear or the program will not run, send the report file if there
is one, and the text from the command prompt if there is not.
