Clarify docs on API authentication

RESOLVED FIXED

Status

defect
RESOLVED FIXED
3 years ago
3 months ago

People

(Reporter: emorley, Assigned: dustin)

Tracking

Details

(Reporter)

Description

3 years ago
Whilst working on bug 1032163 there were a few things I spotted in the docs that could be tweaked to avoid confusion, so making a note of these here.

* Whilst on https://docs.taskcluster.net/reference/platform/auth/api-docs , it wasn't clear how one should authenticate with the various APIs. It would be great to add an entry to the table of contents for the 'Reference' section that covers Hawk authentication, what headers to set etc (or just linking to https://docs.taskcluster.net/manual/apis if that's the most appropriate place - I just didn't see that straight away, since it was in the 'Manual' section rather than 'Reference')

* https://docs.taskcluster.net/manual/apis mentions that the clientId and accessToken are used with Hawk but doesn't go into details. Is accessToken the hawk parameter called 'key'? ie there's more details on temporary credentials (on https://docs.taskcluster.net/manual/apis/temporary-credentials) than there are on 'normal' credentials. The answer here might just be to use the official clients - if so, perhaps we should explicitly state that the official clients should be used.

* On https://docs.taskcluster.net/manual/apis/temporary-credentials the attribute `temporaryAccessToken` is mentioned several times, however the response from login.taskcluster.net (which are supposedly temporary credentials) instead still uses the attribute `accessToken`. Should the docs actually be referring to:
'temporary `accessToken`'
...rather than:
'`temporaryAccessToken`'  ?

* On https://docs.taskcluster.net/manual/apis it mentions that credentials are 'sometimes' accompanied by a certificate, is this just for temporary credentials? If so, it would be good to state that. (https://docs.taskcluster.net/manual/apis/temporary-credentials would imply so).

* On https://docs.taskcluster.net/manual/apis/temporary-credentials it says:
"A set of temporary credentials cannot be used to issue new temporary credentials"
...and then on https://github.com/taskcluster/taskcluster-login/blob/master/README.md :
"This service provides a very minimal UI that users can authenticate against and then get temporary credentials issued."
...however the scopes returned in the certificate generated on https://login.taskcluster.net/ , includes:
auth:create-client:mozilla-ldap/emorley@mozilla.com/*
...which seems to contradict the "cannot create new credentials"?

* New temporary credentials generated by https://login.taskcluster.net/ don't appear on https://tools.taskcluster.net/auth/clients/ . Presuming this is expected, it would be good to mention that on https://docs.taskcluster.net/manual/apis/clients and likely also on the Client Manager tool page too. Side note: how does one go about seeing what temporary credentials are active? Or is that not possible?

* Reading https://docs.taskcluster.net/reference/platform/auth/api-docs it's not clear which endpoint I should be using to verify the callback generated from eg https://login.taskcluster.net/?target=https://treeherder.mozilla.org/&description=Treeherder . The first one that stood out was https://docs.taskcluster.net/reference/platform/auth/api-docs#authenticateHawk however that operates on a provided URL, which isn't what we want. The other I guess is https://docs.taskcluster.net/reference/platform/auth/api-docs#currentScopes where we can both check the validity of the user's accessToken, and also retrieve the expanded list of scopes. Perhaps the recommended endpoint could be mentioned on https://github.com/taskcluster/taskcluster-login/blob/master/README.md#access-grant-for-tools
(Reporter)

Comment 1

3 years ago
I'm happy to open some PRs for these once I have a better understanding of the above :-)
Flags: needinfo?(dustin)
(Reporter)

Comment 2

3 years ago
* On https://github.com/taskcluster/taskcluster-client.py#methods-in-taskclusterauth there's:
```
// Create Auth client instance
import taskcluster
auth = taskcluster.Auth(options)
```
...however it's not really explained anywhere what `options` should (or can) contain.

By experimentation I found that it should be the credentials, but it would be good to mention this explicitly.

(In reply to Ed Morley [:emorley] from comment #0)
> * New temporary credentials generated by https://login.taskcluster.net/
> don't appear on https://tools.taskcluster.net/auth/clients/ . Presuming this
> is expected, it would be good to mention that on
> https://docs.taskcluster.net/manual/apis/clients and likely also on the
> Client Manager tool page too. Side note: how does one go about seeing what
> temporary credentials are active? Or is that not possible?

Similarly, the python client gives:

>>> auth.client('mozilla-ldap/emorley@mozilla.com')
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/home/Ed/.virtualenvs/tc/lib/python2.7/site-packages/taskcluster/sync/Auth.py", line 119, in client
    return self.makeHttpRequest('get', route)
  File "/home/Ed/.virtualenvs/tc/lib/python2.7/site-packages/taskcluster/sync/syncclient.py", line 60, in makeHttpRequest
    return self._makeHttpRequest(method, url, payload, headers)
  File "/home/Ed/.virtualenvs/tc/lib/python2.7/site-packages/taskcluster/sync/syncclient.py", line 92, in _makeHttpRequest
    self._raiseHttpError(status, data, rerr)
  File "/home/Ed/.virtualenvs/tc/lib/python2.7/site-packages/taskcluster/baseclient.py", line 337, in _raiseHttpError
    superExc=rerr
taskcluster.exceptions.TaskclusterRestFailure: Client not found! - {
    "message": "Client not found!"
}
(Reporter)

Updated

3 years ago
Blocks: 1273034
No longer blocks: 1032163
Assignee: nobody → dustin
Flags: needinfo?(dustin)
> ...which seems to contradict the "cannot create new credentials"?

it can create new credentials, just not *temporary* credentials.
> Side note: how does one go about seeing what temporary credentials are active? Or is that not possible?

No, temp credentials are entirely ephemeral and can't be listed or seen anywhere.

Regarding the client docs, I have plans to fold those into the docs site, rather than leaving them in READMEs, at which point I'll better define `options` and the like.
Status: NEW → RESOLVED
Last Resolved: 3 years ago
Resolution: --- → FIXED
(Reporter)

Comment 7

3 years ago
Thank you for these changes - they help a lot.

(In reply to Dustin J. Mitchell [:dustin] from comment #4)
> No, temp credentials are entirely ephemeral and can't be listed or seen
> anywhere.

Ah that was the piece I was missing. I initially thought temporary credentials were just standard credentials with a subset of scope and also an expiry time, but I see they are really 'standalone credentials', which explains the signature.
Component: Documentation → Services
Product: Taskcluster → Taskcluster
You need to log in before you can comment on or make changes to this bug.