3. Authentication

RESTful provides several authentication methods out-of-the-box; basic-auth, cookie, and token. Which you choose (if any) depends on a number of factors.

The cookies authentication will only work if your client will be served from the same domain as Drupal is running on.

If your client is fully-decoupled (e.g. served from a different domain, or running as an app on a device), you will need to use token-based authentication. You must then consider the security implications of storing this token on the device. For example, it may not be wise to store this token in a browser's local storage.

Using login endpoint, with cookies

You will need to have Drupal give you an authentication cookie either by manually logging in to your Drupal site, or via the api/v1.0/login endpoint (see more).

Once your client has the auth cookie, it can send that back with every request and Drupal will know the REST request has come from an authenticated user.

Using token-auth module

The RESTful project comes with the optional RESTful token authentication module, which allows you to authenticate a REST call using a token. To use token authentication in 2.x, you'll need to specify it as your resource's authentication method in its annotation, since all methods are available to your API's consumers by default:

 *   authenticationTypes = {
 *     "token"
 *   },

The endpoint for this is api/login-token (read more). For customizing this endpoint, see this example on how to extend and modify its behaviour, such as disabling cookie authentication.

Once your client has obtained the authentication token, it can send that back with each request, so that Drupal knows the request is from the authenticated user. For example, your request would include this header :

access_token: 1BN31E7saCPxnUr3dxFmFoEzl6rsrgk17487s6GOOhg

Use access-token instead of access_token for ensuring header is not going to be dropped out from $_SERVER so it remains compatible with other webservers different than apache. See Working with authentication providers

Example written in Angular: https://github.com/Gizra/angular-restful-auth

If you intend to do this in conjunction with CORS (i.e. from another domain) there is a known issue you should be aware of. See A warning regarding CORS and authenticated resources for more.

Obtaining the current user in custom Drupal module code

If you're using cookie-based auth, Drupal's global $user will accurately reflect the currently authenticated user, even for RESTful requests.

However, if you are using one of the other authentication methods, Drupal won't receive a cookie with the request, and thus won't authenticate. RESTful authenticates separately.

In this situation, if you are writing a custom Drupal module, you will need to ask RESTful for the authenticated user object, rather than using global $user (or any other traditional Drupal-based method for getting the current user).

RESTful allows you to get the currently authenticated user by calling ->getAccount() which is defined in many of its classes. If your custom code is outside of any RESTful class, you can still obtain it as follows:

$resource = restful()->getResourceManager()->negotiate();
$resource->setRequest(restful()->getRequest());
$resource->getAccount();