All requests to the API server must have an API token. API tokens can be issued by going though the login flow, or created via the API. At this time, only browser based applications can perform login from email/password. Command line applications and services must use an API token provided via the ARVADOS_API_TOKEN
environment variable or configuration file.
Browser based applications can log in using one of the two possible flows:
/login
endpoint on the API server. This link should include the return_to
parameter in the query portion of the URL. For example https://pirca.arvadosapi.com/login?return_to=XXX
, where return_to=XXX
is a page in the web application./login
endpoint redirects the user to the configured third party authentication provider (e.g. Google or other OpenID Connect provider).return_to=XXX
with the addition of ?api_token=xxxxapitokenxxxx
./arvados/v1/users/authenticate
application/javascript
username
and password
fields.api_client_authorization
object for the new API token.A cluster that uses OpenID Connect as a login provider can be configured to accept OIDC access tokens as well as Arvados API tokens (this is disabled by default; see Login.OpenIDConnect.AcceptAccessToken
in the default config.yml file).
Authorization: Bearer xxxxaccesstokenxxxx
).Login.OpenIDConnect.AcceptAccessTokenScope
in the default config.yml file).Creation and activation of new users is described here.
The browser login method above issues a new token. Using that token, it is possible to make API calls to create additional tokens. To do so, use the create
method of the API client authorizations resource.
Scopes can restrict a token so it may only access certain resources. This is in addition to normal permission checks for the user associated with the token.
Each entry in scopes consists of a request_method
and request_path
. The request_method
is a HTTP method (one of GET
, POST
, PATCH
or DELETE
) and request_path
is the request URI. A given request is permitted if it matches a scopes exactly, or the scope ends with /
and the request string is a prefix of the scope.
As a special case, a scope of ["all"]
allows all resources. This is the default if no scope is given.
A valid token is always allowed to issue a request to GET /arvados/v1/api_client_authorizations/current
regardless of its scopes.
Using scopes is also described on the Securing API access with scoped tokens page of the admin documentation.
A scope of GET /arvados/v1/collections
permits listing collections.
POST /arvados/v1/collections
, will be rejected.GET /arvados/v1/groups
, will be rejected (except GET /arvados/v1/api_client_authorizations/current
, which is always allowed).GET /arvados/v1/collections/962eh-4zz18-xi32mpz2621o8km
will also be rejected. This is because the scope GET /arvados/v1/collections
does not end in /
A scope of GET /arvados/v1/collections/
(with /
suffix) will permit access to individual collections.
GET /arvados/v1/collections/962eh-4zz18-xi32mpz2621o8km
will succeedGET /arvados/v1/collections
(no /
suffix) will be rejected, because it is not a match with the rule GET /arvados/v1/collections/
GET /arvados/v1/collections/
will have the trailing /
suffix trimmed before the scope check, as a result it will not match the rule GET /arvados/v1/collections/
.To allow both listing objects and requesting individual objects, include both in the scope: ["GET /arvados/v1/collections", "GET /arvados/v1/collections/"]
A narrow scope such as GET /arvados/v1/collections/962eh-4zz18-xi32mpz2621o8km
will disallow listing objects as well as disallow requesting any object other than those listed in the scope.
The content of this documentation is licensed under the
Creative
Commons Attribution-Share Alike 3.0 United States licence.
Code samples in this documentation are licensed under the
Apache License, Version 2.0.