Add docs for user management and invitations

[evankanderson]

Summary

Document the new user invitations feature

Fixes #3795

Change Type

Mark the type of change your PR introduces:

• Bug fix (resolves an issue without affecting existing features)
• Feature (adds new functionality without breaking changes)
• Breaking change (may impact existing functionalities or require documentation updates)
• Documentation (updates or additions to documentation)
• Refactoring or test improvements (no bug fixes or new functionality)

Testing

N/A

Review Checklist:

• Reviewed my own code for quality and clarity.
• Added comments to complex or tricky code sections.
• Updated any affected documentation.
• Included tests that validate the fix or feature.
• Checked that related changes are merged.

[evankanderson]

Note: I ended up running prettier on some of the code and it fixed up some of the inconsistent spacing. I undid some of the larger changes, but didn't get them all. I can move all to a separate PR if desired.

[puerco]

Thanks @evankanderson , just a small nit, feel free to ignore

[rdimitrov]

Unfortunately this is not like that right now. We still create a project, we just don't go through the onboarding flow and also show by default the oldest project in the UI (which is the one the user accepted the invite for).

We had a discussion with @jhrozek that we should separate the project creation part from the user creation part, ref. #3826 (implying changes on the client's side - UI and CLI)

[evankanderson]

@ethomson -- are we okay shipping invitations with this change from the PRD & tech design, or do we need to address it before release?

[rdimitrov]

Another note - if the user accepted an invite, but then selects their default project from the drop down menu they will be taken through the onboarding flow for it since it's what the front end does for every new project.

[ethomson]

• I think it's really surprising that we new up a secret project behind the scenes that nobody asked for.
• We have a metric around project creation and how many have rules and profiles associated with them (versus not), and this will annihilate that metric. 🙃
• The UI should show the most recent project, not the oldest project. (Again, the FE needs a data store for its own business logic, and doesn't have one.)

Can you give me a rough cost on separating user creation from project creation?

[evankanderson]

I think we need to figure out what the API call is that creates the user without the project. I need to look and see if it makes sense for ResolveInvitation to potentially set up a new user if it's called by someone who is known to Keycloak but not to Minder. If so, the flow for getting a Minder account would be either:

ResolveInvitation -> ...

OR

CreateUser -> ...

Right now we're measuring projects primarily, so we probably wouldn't really "see" the additional users on a project from a metrics PoV, which may be okay in general.

The interesting question is what middleware and other plumbing might break by making ResolveInvitation not require a User object already stored in the database.

[evankanderson]

I think this will be a small change, if I'm right, I'm about 2/3rds done now (plus tests, so really 40% done).

[evankanderson]

I made it a medium-size change, and it will need a client release: #3909

[evankanderson]

Also @kantord for a heads-up; I commented on #3909, but the frontend should not call CreateUser before calling ResolveInvitation -- ResolveInvitation will take care of any bookkeeping needed in terms of getting user information. Note that before calling ResolveInvitation, the GetUser call will also fail.