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:
/loginendpoint on the API server. This link should include the
return_toparameter in the query portion of the URL. For example
return_to=XXXis a page in the web application.
/loginendpoint redirects the user to the configured third party authentication provider (e.g. Google or other OpenID Connect provider).
return_to=XXXwith the addition of
api_client_authorizationobject 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.AcceptAccessTokenScopein the default config.yml file).
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.
The api_clients resource determines if web applications that have gone through the browser login flow may create or list API tokens.
After the user has authenticated, but before an authorization token is issued and browser redirect sent (sending the browser back to the
return_to login page bearing
api_token), the server strips the path and query portion from
return_to to get
url_prefix is used to find or create an ApiClient object. The newly issued API client authorization (API token) is associated with this ApiClient object.
API clients may be marked as “trusted” by making an API call to create or update an api_clients resource and set the
is_trusted flag to
true. An authorization token associated with a “trusted” client is permitted to list authorization tokens on API client authorizations .
A authorization token which is not associated with a trusted client may only use the
current method to query its own api_client_authorization object. The “untrusted” token is forbidden performing any other operations on API client authorizations, such as listing other authorizations or creating new authorizations.
Authorization tokens which are not issued via the browser login flow (created directly via the API) inherit the api client of the token used to create them. They will always be “trusted” because untrusted API clients cannot create tokens.
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 is a HTTP method (one of
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-xi32mpz2621o8kmwill also be rejected. This is because the scope
GET /arvados/v1/collectionsdoes not end in
A scope of
GET /arvados/v1/collections/ (with
/ suffix) will permit access to individual collections.
GET /arvados/v1/collections/962eh-4zz18-xi32mpz2621o8kmwill succeed
/suffix) will be rejected, because it is not a match with the rule
GET /arvados/v1/collections/will have the trailing
/suffix trimmed before the scope check, as a result it will not match the rule
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
Commons Attribution-Share Alike 3.0 United States licence.
Code samples in this documentation are licensed under the Apache License, Version 2.0.