Fully document all the UI endpoints

[MrCreosote]

Currently only the endpoints for the start of a user flow are documented in the readme, and furthermore their signatures are not documented. Further endpoints and their signatures are discoverable by traversing the user flow from the starting endpoint, but should also be fully documented.

[MrCreosote]

Doing some Q&D login documentation here (linking is almost identical, just replace login with link in the urls). For all these cases I'd also recommend examining the current calls in the UI codebase and seeing how the calls are made in practice. I'm leaving out some optional parameters that I think aren't used.

Start login with a provider (one of Google, Globus, or OrcID):

~$ curl -v -d 'provider=Google' https://ci.kbase.us/services/auth/login/start/ 2>&1 |  grep Location
< Location: https://accounts.google.com/o/oauth2/v2/auth?scope=profile+email&state=[*snip*]&redirect_uri=https%3A%2F%2Fci.kbase.us%2Fservices%2Fauth%2Flogin%2Fcomplete%2Fgoogle&response_type=code&client_id=[*snip*]&prompt=select_account

There's a few other optional parameters including submitting a redirect url for post login use.

That sends the user to Google (or whoever) to complete the login, at which point the user is redirected back to the kbase auth2 server, which sets some temporary cookies and redirects back to the UI.

The UI then accesses the choice endpoint (which currently will never present a choice... but anyway) to get the kbase identity ID for the 3rd party identity. Note that in a browser based environment explicitly sending the token is not necessary, and the token can and should be ignored.

$ curl -H "accept: application/json" --cookie "in-process-login-token=$IN_PROCESS_TOKEN" https://ci.kbase.us/services/auth/login/choice | python -m json.tool
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100   559  100   559    0     0   2973      0 --:--:-- --:--:-- --:--:--  2973
{
    "cancelurl": "cancel",
    "create": [],
    "createurl": "create",
    "creationallowed": true,
    "expires": 1662501014716,
    "login": [
        {
            "adminonly": false,
            "disabled": false,
            "id": "ID goes here",
            "loginallowed": true,
            "policyids": [
                {
                    "agreedon": 1490373879406,
                    "id": "data-policy.3"
                },
                {
                    "agreedon": 1496872870800,
                    "id": "data-policy.1"
                },
                {
                    "agreedon": 1490373879405,
                    "id": "kbase-user.2"
                },
                {
                    "agreedon": 1496872870802,
                    "id": "kbase-user.1"
                }
            ],
            "provusernames": [
                "google email address in this case"
            ],
            "user": "gaprice"
        }
    ],
    "pickurl": "pick",
    "provider": "Google",
    "redirecturl": null,
    "suggestnameurl": "suggestname"
}

If the user already has an account the response will look like this, with the create field empty and the login field containing an entry. create will be covered later in this issue.

To cancel the login and clean up temporary cookies, send a DELETE to the /login/cancel endpoint.

Finally the UI accesses the pick endpoint to get a login token:

$ curl -H "content-type: application/json" -H "accept: application/json" --cookie "in-process-login-token=$IN_PROCESS_TOKEN" -d '{"id":"ID goes here","policyids":["fake_policy_id"]}' https://ci.kbase.us/services/auth/login/pick | python -m json.tool
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100   383  100   311  100    72    182     42  0:00:01  0:00:01 --:--:--   224
{
    "redirecturl": null,
    "token": {
        "agent": "curl",
        "agentver": "7.58.0",
        "created": 1662500686778,
        "custom": {},
        "device": null,
        "expires": 1663710286778,
        "id": "90a869a7-b925-4e31-b207-1d0ddbe1a86a",
        "ip": "42.42.42.42",
        "name": null,
        "os": null,
        "osver": null,
        "token": "token here",
        "type": "Login",
        "user": "gaprice"
    }
}

[MrCreosote]

For the case where the choice endpoint returns a create rather than a login entry:

$ curl -H "accept: application/json" --cookie "in-process-login-token=$IN_PROCESS_TOKEN" https://ci.kbase.us/services/auth/login/choice | python -m json.tool
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100   416  100   416    0     0    883      0 --:--:-- --:--:-- --:--:--   881
{
    "cancelurl": "cancel",
    "create": [
        {
            "availablename": "A name based off the provider username that is currently available in kbase, although this info is immediately stale",
            "id": "ID goes here",
            "provemail": "provider email address,
            "provfullname": "provider full name",
            "provusername": "provider user name"
        }
    ],
    "createurl": "create",
    "creationallowed": true,
    "expires": 1662503169057,
    "login": [],
    "pickurl": "pick",
    "provider": "Google",
    "redirecturl": null,
    "suggestnameurl": "suggestname"
}

In this case, the UI sends the user details to the create endpoint:

$ curl -H "content-type: application/json" -H "accept: application/json" --cookie "in-process-login-token=$IN_PROCESS_TOKEN" -d '{"id":"ID goes here","policyids":["fake_policy_id"],"user":"deliberately illegal $username","display":"display name","email":"[email protected]"}' https://ci.kbase.us/services/auth/login/create | python -m json.tool
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100   421  100   251  100   170    517    350 --:--:-- --:--:-- --:--:--   868
{
    "error": {
        "appcode": 30010,
        "apperror": "Illegal user name",
        "callid": "0258713686573838",
        "httpcode": 400,
        "httpstatus": "Bad Request",
        "message": "30010 Illegal user name: Illegal character in user name deliberately illegal $username:  ",
        "time": 1662502300917
    }
}

A successful response looks identical to the pick endpoint result.

[MrCreosote]

Getting a name suggestion:

$ curl https://ci.kbase.us/services/auth/login/suggestname/some%20user$name
{"availablename":"someuser"}