Making a call to a protected Taskcluster API requires a user to be logged in. The full process consists of:
- Using a login strategy to acquire an access token.
- Exchanging the access token for Taskcluster credentials.
- Calling Taskcluster APIs using the user's Taskcluster credentials.
Let's walk through each process.
The purpose of using a login strategy is to produce an access token to be used in the next step. Taskcluster currently supports the following login strategies:
-
GitHub - This lets a user login using GitHub. To configure the strategy, you will need to register an application with GitHub. If you don’t have one, you can create one at developer applications within GitHub’s setting panel. Once the application is created, be sure to follow the guidelines to enable the
github
strategy. -
Mozilla Auth0 - To configure the strategy, you will need to possess an auth0 Client which can access Taskcluster credentials. If you don't have one, you can request a New Single Sign On Application in The Hub. Make sure to request a client that uses "RS256 algorithms" and "OpenIDConnect (OIDC)”. Once the client is created, be sure to follow the guidelines to enable the
mozilla-auth0
strategy.
All of the strategies use the OAuth 2.0 protocol to authenticate. OAuth 2.0 is a framework that allows users to grant limited access to their information to a website without giving them the password.
In order to enable a specific strategy, changes to both
taskcluster-ui
and web-server
are required. The changes are outlined in
taskcluster-ui's (login strategies) and
web-server (login strategies).
-
The front-end application initiates the login process by sending a request to
/login/<strategy>
in a new browser window. Sincetaskcluster-ui
is a single page application, there should be a proxy directing requests starting with/login
to the server in order not to have the request be misinterpreted as a client-side route change. -
The web server gateway triggers the middleware that corresponds to the specified strategy in the request. The middleware is responsible of redirecting the request to the provider page where the user will login as well as setting the
callbackUrl
to<public-url>/login/<strategy-name>/callback
. ThecallbackUrl
is a URL where the application will receive and process the response once the authentication is complete. In our case, we handle the response in the server. -
The
callbackUrl
goes through the proxy mentioned in step 1 and triggers the callback middleware in the web server. The callback function is responsible for communicating the user’s information to the front-end application via the Web APIwindow.postMessage
incallback.ejs
(https://github.com/taskcluster/taskcluster/blob/master/services/web-server/src/views/callback.ejs). For the message to be received successfully, the front-end application needs to be listening to themessage
event.
Example: Listening to the message
event of type login
window.addEventListener(‘message', function handler(e) {
if (e.origin !== window.origin || !e.data || e.data.type !== ‘login’) {
return;
}
const { type, profile, identityProviderId, accessToken } = e.data;
// ...
});
Authenticating with a login strategy returns back an access token to the caller.
To get Taskcluster credentials, the caller must make a request to
the graphQL getCredentials
endpoint, including the accessToken
and provider
.
The accessToken
will be verified against the provider
.
The response will contain Taskcluster credentials corresponding to a temporary client.
The Taskcluster credentials have a very short expiration, but can be requested again
when required. Callers should check the expiration before every call to a
Taskcluster API and refresh when necessary. To pass credentials, the caller must
include the Authorization
header of type Bearer
with Taskcluster credentials
encoded in base-64. In taskcluster-ui
, this is codified in
here.