An oauth server error was encountered that did not contain a json body

I have been attempting to develop an API and client which communicate to each other via an implementation of ThePHPLeague’s OAuth2 server and client. Using the curl command in a CLI, I am able to generate a token and use it to gain access to protected resources.

User authentication relies on a bespoke PHP solution with Slim framework, which accepts a username and encrypted password stored in a database table. The same table is used for the OAuth2 implementation’s user management.

When a user login attempt is successfully validated, the AbstractProvider ‘s getAccessToken() method is called and an access token is requested from the API. Here is where the problem lies.

I have tested functionality using the GenericProvider class. I’ve also extended the provider to create my own class. Using the both providers, I see the following error when I attempt to login:

Slim Application Error
Type: UnexpectedValueException
Code: 0
Message: An OAuth server error was encountered that did not contain a JSON body
File: /var/www/sloth2-client-php/vendor/league/oauth2-client/src/Provider/AbstractProvider.php
Line: 693

#0 /.../vendor/league/oauth2-client/src/Provider/AbstractProvider.php(626): 
LeagueOAuth2ClientProviderAbstractProvider->parseResponse(Object(GuzzleHttpPsr7Response))
#1 /.../src/SlothProvider.php(113): LeagueOAuth2ClientProviderAbstractProvider->getParsedResponse(Object(GuzzleHttpPsr7Request))
#2 /.../src/Controller/AuthenticationController.php(69): AppSlothProvider->getAccessToken(Object(LeagueOAuth2ClientGrantClientCredentials))
#3 /.../vendor/slim/slim/Slim/Handlers/Strategies/RequestResponse.php(42): AppControllerAuthenticationController->authenticate(Object(SlimPsr7Request), Object(SlimPsr7Response), Array)
#4 /.../vendor/slim/slim/Slim/Routing/Route.php(372): SlimHandlersStrategiesRequestResponse->__invoke(Array, Object(SlimPsr7Request), Object(SlimPsr7Response), Array)
#5 /.../vendor/slim/slim/Slim/MiddlewareDispatcher.php(73): SlimRoutingRoute->handle(Object(SlimPsr7Request))
#6 /.../vendor/slim/slim/Slim/MiddlewareDispatcher.php(73): SlimMiddlewareDispatcher->handle(Object(SlimPsr7Request))
#7 /.../vendor/slim/slim/Slim/Routing/Route.php(333): SlimMiddlewareDispatcher->handle(Object(SlimPsr7Request))
#8 /.../vendor/slim/slim/Slim/Routing/RouteRunner.php(65): SlimRoutingRoute->run(Object(SlimPsr7Request))
#9 /.../vendor/slim/slim/Slim/Middleware/RoutingMiddleware.php(58): SlimRoutingRouteRunner->handle(Object(SlimPsr7Request))
#10 /.../vendor/slim/slim/Slim/MiddlewareDispatcher.php(132): SlimMiddlewareRoutingMiddleware->process(Object(SlimPsr7Request), Object(SlimRoutingRouteRunner))
#11 /.../vendor/slim/slim/Slim/Middleware/ErrorMiddleware.php(89): class@anonymous->handle(Object(SlimPsr7Request))
#12 /.../vendor/slim/slim/Slim/MiddlewareDispatcher.php(132): SlimMiddlewareErrorMiddleware->process(Object(SlimPsr7Request), Object(class@anonymous))
#13 /.../vendor/slim/slim/Slim/MiddlewareDispatcher.php(73): class@anonymous->handle(Object(SlimPsr7Request))
#14 /.../vendor/slim/slim/Slim/App.php(206): SlimMiddlewareDispatcher->handle(Object(SlimPsr7Request))
#15 /.../vendor/slim/slim/Slim/App.php(190): SlimApp->handle(Object(SlimPsr7Request))
#16 /.../public/index.php(8): SlimApp->run()
#17 {main}

The SlothProvider class mentioned in the stack trace is as follows:

<?php

namespace App;

use LeagueOAuth2ClientProviderAbstractProvider;
use LeagueOAuth2ClientTokenAccessToken;
use LeagueOAuth2ClientToolBearerAuthorizationTrait;
use PsrHttpMessageResponseInterface;
use UnexpectedValueException;

class SlothProvider extends AbstractProvider
{
  use BearerAuthorizationTrait;

  public function __construct()
  {
    $this->clientId = getenv('OAUTH2_CLIENT_ID');
    $this->clientSecret = getenv('OAUTH2_CLIENT_SECRET');
    $this->redirectUri = getenv('OAUTH2_REDIRECT_URI');
  }

  /**
   * Get authorization url to begin OAuth flow
   *
   * @return string
   */
  public function getBaseAuthorizationUrl()
  {
    return getenv('OAUTH2_AUTHORIZATION_URL');
  }

  /**
   * Get access token url to retrieve token
   *
   * @param  array $params
   *
   * @return string
   */
  public function getBaseAccessTokenUrl(array $params)
  {
    return getenv('OAUTH2_ACCESS_TOKEN_URL');
  }

  /**
   * Get provider url to fetch user details
   *
   * @param  AccessToken $token
   *
   * @return string
   */
  public function getResourceOwnerDetailsUrl(AccessToken $token)
  {
    // You don't have one. You might consider throwing an exception here so
    // that, when this is called, you get an error and can code your
    // application to ensure that nothing calls this.
    //
    // Note that $this->getResourceOwner() is the most likely culprit for
    // calling this. Just don't call getResourceOwner() in your code.
  }

  /**
   * Get the default scopes used by this provider.
   *
   * This should not be a complete list of all scopes, but the minimum
   * required for the provider user interface!
   *
   * @return array
   */
  protected function getDefaultScopes()
  {
    return ['basic'];
  }

  /**
   * Check a provider response for errors.
   *
   * @throws IdentityProviderException
   * @param  ResponseInterface $response
   * @param  array $data Parsed response data
   * @return void
   */
  protected function checkResponse(ResponseInterface $response, $data)
  {
    // Write code here that checks the response for errors and throws
    // an exception if you find any.
  }

  /**
   * Generate a user object from a successful user details request.
   *
   * @param array $response
   * @param AccessToken $token
   * @return LeagueOAuth2ClientProviderResourceOwnerInterface
   */
  protected function createResourceOwner(array $response, AccessToken $token)
  {
    // Leave empty. You can't use this, since you don't have a clear
    // resource owner details URL. You might consider throwing an
    // exception from here, as well. See note on
    // getResourceOwnerDetailsUrl() above.
  }

  /**
   * Requests an access token using a specified grant and option set.
   *
   * @param  mixed $grant
   * @param  array $options
   * @throws IdentityProviderException
   * @return AccessTokenInterface
   */
  public function getAccessToken($grant, array $options = [])
  {
    $grant = $this->verifyGrant($grant);
    $params = [
      'client_id'     => $this->clientId,
      'client_secret' => $this->clientSecret,
      'redirect_uri'  => $this->redirectUri,
    ];
    $params   = $grant->prepareRequestParameters($params, $options);
    $request  = $this->getAccessTokenRequest($params);
    $response = $this->getParsedResponse($request);
    if (false === is_array($response)) {
      throw new UnexpectedValueException(
        'Invalid response received from Authorization Server. Expected JSON.'
      );
    }
    $prepared = $this->prepareAccessTokenResponse($response);
    $token    = $this->createAccessToken($prepared, $grant);
    return $token;
  }
}

I would like to know what this error means and how to solve it.

As this issue is still open, I’d like to raise some concern and share my thought.
This is how it is currently implemented

public function getParsedResponse(RequestInterface $request)
{
    try {
        $response = $this->getResponse($request);
    } catch (BadResponseException $e) {
        $response = $e->getResponse();
    }

    $parsed = $this->parseResponse($response);

    $this->checkResponse($response, $parsed);

    return $parsed;
}

I assume the intended task of parseResponse() is to correctly parse the response body and return it. Currently, parseResponse is able to parse urlencoded or valid json body. In general, the result of a json parsing does not need to be an array. It could even be null, empty string, integer, etc. So the value of $parsed can be of different type, which I don’t really care much. It is up to the calling function to correctly handle that value.

/**
 * Parses the response according to its content-type header.
 *
 * @throws UnexpectedValueException
 * @param  ResponseInterface $response
 * @return array
 */
protected function parseResponse(ResponseInterface $response)
{
    $content = (string) $response->getBody();
    $type = $this->getContentType($response);

    if (strpos($type, 'urlencoded') !== false) {
        parse_str($content, $parsed);
        return $parsed;
    }

    // Attempt to parse the string as JSON regardless of content type,
    // since some providers use non-standard content types. Only throw an
    // exception if the JSON could not be parsed when it was expected to.
    try {
        return $this->parseJson($content);
    } catch (UnexpectedValueException $e) {
        if (strpos($type, 'json') !== false) {
            throw $e;
        }

        if ($response->getStatusCode() == 500) {
            throw new UnexpectedValueException(
                'An OAuth server error was encountered that did not contain a JSON body',
                0,
                $e
            );
        }

        return $content;
    }
}

The @return array type hint is surely wrong.

The problem with current implementation of parseResponse() is that it throws an exception which does not help much in the calling function if the response body cannot be parsed as JSON. This includes body having empty string as value.
Thus, I’d suggest to throw a new exception type called ResponseParsingException which encapsulates the response and its body, so that the calling function can reacts accordingly by retrieving the response and/or the body from the catched exception.
To ensure BC we can define a flag in AbstractProvider, e.g.

protected $mayThrowResponseParsingException = false;

which can be used to control the behavior of parseResponse().

 /**
 * Parses the response according to its content-type header.
 *
 * @throws UnexpectedValueException
 * @throws ResponseParsingException if the flag $mayThrowResponseParsingException is true and
 *                                  response body cannot be parsed.
 * @param  ResponseInterface $response
 * @return array|string
 */
protected function parseResponse(ResponseInterface $response)
{
    $content = (string) $response->getBody();
    $type = $this->getContentType($response);

    if (strpos($type, 'urlencoded') !== false) {
        parse_str($content, $parsed);
        return $parsed;
    }

    // Attempt to parse the string as JSON regardless of content type,
    // since some providers use non-standard content types. Only throw an
    // exception if the JSON could not be parsed when it was expected to.
    try {
        return $this->parseJson($content);
    } catch (UnexpectedValueException $e) {
        if (strpos($type, 'json') !== false) {
            throw $this->mayThrowResponseParsingException
                ? new ResponseParsingException($response, $content, $e->getMessage(), $e->getCode())
                : $e;
        }

        // for any other content types
        if ($this->mayThrowResponseParsingException) {
            // let the calling function decide what to do with the response and its body
            throw new ResponseParsingException($response, $content, '', 0);
        } else {
            if ($response->getStatusCode() == 500) {
                throw new UnexpectedValueException(
                    'An OAuth server error was encountered that did not contain a JSON body',
                    0,
                    $e
                );
            }

            return $content;
        }
    }
}

`
What do you think?
I know that the method checkResponse() can be (mis)used to re-parse the response later. But this is most probably not what this method is supposed to do. I assume that checkResponse should be used to check for error messages in the successfully parsed body returned by a well-behaved identity provider.

На хабре уже писали про OAuth 1.0, но понятного объяснения того, что такое OAuth 2.0 не было. Ниже я расскажу, в чем отличия и преимущества OAuth 2.0 и, как его лучше использовать на сайтах, в мобильных и desktop-приложениях.

Что такое OAuth 2.0

OAuth 2.0 — протокол авторизации, позволяющий выдать одному сервису (приложению) права на доступ к ресурсам пользователя на другом сервисе. Протокол избавляет от необходимости доверять приложению логин и пароль, а также позволяет выдавать ограниченный набор прав, а не все сразу.

Чем отличаются OpenID и OAuth

Не смотря на то, что объяснений на эту тему уже было много, она по-прежнему вызывает некоторое непонимание.

OpenID предназначен для аутентификации — то есть для того, чтобы понять, что этот конкретный пользователь является тем, кем представляется. Например, с помощью OpenID некий сервис Ололо может понять, что зашедший туда пользователь, это именно Рома Новиков с Mail.Ru. При следующей аутентификации Ололо сможет его опять узнать и понять, что, это тот же Рома, что и в прошлый раз.

OAuth же является протоколом авторизации, то есть позволяет выдать права на действия, которые сам Ололо сможет производить в Mail.Ru от лица Ромы. При этом Рома после авторизации может вообще не участвовать в процессе выполнения действий, например, Ололо сможет самостоятельно заливать фотографии на Ромин аккаунт.

Как работает OAuth 2.0

Как и первая версия, OAuth 2.0 основан на использовании базовых веб-технологий: HTTP-запросах, редиректах и т. п. Поэтому использование OAuth возможно на любой платформе с доступом к интернету и браузеру: на сайтах, в мобильных и desktop-приложениях, плагинах для браузеров…

Ключевое отличие от OAuth 1.0 — простота. В новой версии нет громоздких схем подписи, сокращено количество запросов, необходимых для авторизации.

Общая схема работы приложения, использующего OAuth, такова:

1. получение авторизации
2. обращение к защищенным ресурсам

Результатом авторизации является access token — некий ключ (обычно просто набор символов), предъявление которого является пропуском к защищенным ресурсам. Обращение к ним в самом простом случае происходит по HTTPS с указанием в заголовках или в качестве одного из параметров полученного access token‘а.

В протоколе описано несколько вариантов авторизации, подходящих для различных ситуаций:

• авторизация для приложений, имеющих серверную часть (чаще всего, это сайты и веб-приложения)
• авторизация для полностью клиентских приложений (мобильные и desktop-приложения)
• авторизация по логину и паролю
• восстановление предыдущей авторизации

Авторизация для приложений, имеющих серверную часть

1. Редирект на страницу авторизации
2. На странице авторизации у пользователя запрашивается подтверждение выдачи прав
3. В случае согласия пользователя, браузер редиректится на URL, указанный при открытии страницы авторизации, с добавлением в GET-параметры специального ключа — authorization code
4. Сервер приложения выполняет POST-запрос с полученным authorization code в качестве параметра. В результате этого запроса возвращается access token

Это самый сложный вариант авторизации, но только он позволяет сервису однозначно установить приложение, обращающееся за авторизацией (это происходит при коммуникации между серверами на последнем шаге). Во всех остальных вариантах авторизация происходит полностью на клиенте и по понятным причинам возможна маскировка одного приложения под другое. Это стоит учитывать при внедрении OAuth-аутентификации в API сервисов.

Пример

Здесь и далее примеры приводятся для API Mail.Ru, но логика одинаковая для всех сервисов, меняются только адреса страниц авторизации. Обратите внимание, что запросы надо делать по HTTPS.

Редиректим браузер пользователя на страницу авторизации:

> GET /oauth/authorize?response_type=code&client_id=464119&
      redirect_uri=http%3A%2F%2Fexample.com%2Fcb%2F123 HTTP/1.1
> Host: connect.mail.ru

Здесь и далее, client_id и client_secret — значения, полученные при регистрации приложения на платформе.

После того, как пользователь выдаст права, происходит редирект на указанный redirect_uri:

< HTTP/1.1 302 Found
< Location: http://example.com/cb/123?code=DoRieb0y

Обратите внимание, если вы реализуете логин на сайте с помощью OAuth, то рекомендуется в redirect_uri добавлять уникальный для каждого пользователя идентификатор для предотвращения CSRF-атак (в примере это 123). При получении кода надо проверить, что этот идентификатор не изменился и соответствует текущему пользователю.

Используем полученный code для получения access_token, выполняя запрос с сервера:

> POST /oauth/token HTTP/1.1
> Host: connect.mail.ru
> Content-Type: application/x-www-form-urlencoded
> 
> grant_type=authorization_code&client_id=464119&client_secret=deadbeef&code=DoRieb0y&
  redirect_uri=http%3A%2F%2Fexample.com%2Fcb%2F123

< HTTP/1.1 200 OK
< Content-Type: application/json
<
< {
<    "access_token":"SlAV32hkKG",
<    "token_type":"bearer",
<    "expires_in":86400,
<    "refresh_token":"8xLOxBtZp8",
< }

Обратите внимание, что в последнем запросе используется client_secret, который в данном случае хранится на сервере приложения, и подтверждает, что запрос не подделан.

В результате последнего запроса получаем сам ключ доступа (access_token), время его «протухания&raquo (expires_in), тип ключа, определяющий как его надо использовать, (token_type) и refresh_token о котором будет подробнее сказано ниже. Дальше, полученные данные можно использовать для доступа к защищенным ресурсам, например, API Mail.Ru:

> GET /platform/api?oauth_token=SlAV32hkKG&client_id=464119&format=json&method=users.getInfo&
      sig=... HTTP/1.1
> Host: appsmail.ru

Описание в спецификации

Авторизация полностью клиентских приложений

1. Открытие встроенного браузера со страницей авторизации
2. У пользователя запрашивается подтверждение выдачи прав
3. В случае согласия пользователя, браузер редиректится на страницу-заглушку во фрагменте (после #) URL которой добавляется access token
4. Приложение перехватывает редирект и получает access token из адреса страницы

Этот вариант требует поднятия в приложении окна браузера, но не требует серверной части и дополнительного вызова сервер-сервер для обмена authorization code на access token.

Пример

Открываем браузер со страницей авторизации:

> GET /oauth/authorize?response_type=token&client_id=464119 HTTP/1.1
> Host: connect.mail.ru

После того, как пользователь выдаст права, происходит редирект на стандартную страницу-заглушку, для Mail.Ru это connect.mail.ru/oauth/success.html:

< HTTP/1.1 302 Found
< Location: http://connect.mail.ru/oauth/success.html#access_token=FJQbwq9&token_type=bearer&
            expires_in=86400&refresh_token=yaeFa0gu

Приложение должно перехватить последний редирект, получить из адреса acess_token и использовать его для обращения к защищенным ресурсам.

Описание в спецификации

Авторизация по логину и паролю

Авторизация по логину и паролю представляет простой POST-запрос, в результате которого возвращается access token. Такая схема не представляет из себя ничего нового, но вставлена в стандарт для общности и рекомендуется к применению только, когда другие варианты авторизации не доступны.

Пример

> POST /oauth/token HTTP/1.1
> Host: connect.mail.ru
> Content-Type: application/x-www-form-urlencoded
> 
> grant_type=password&client_id=31337&client_secret=deadbeef&username=api@corp.mail.ru&
  password=qwerty

< HTTP/1.1 200 OK
< Content-Type: application/json
<
< {
<    "access_token":"SlAV32hkKG",
<    "token_type":"bearer",
<    "expires_in":86400,
<    "refresh_token":"8xLOxBtZp8",
< }

Описание в спецификации

Восстановление предыдущей авторизации

Обычно, access token имеет ограниченный срок годности. Это может быть полезно, например, если он передается по открытым каналам. Чтобы не заставлять пользователя проходить авторизацию после истечения срока действия access token‘а, во всех перечисленных выше вариантах, в дополнение к access token‘у может возвращаться еще refresh token. По нему можно получить access token с помощью HTTP-запроса, аналогично авторизации по логину и паролю.

Пример

> POST /oauth/token HTTP/1.1
> Host: connect.mail.ru
> Content-Type: application/x-www-form-urlencoded
> 
> grant_type=refresh_token&client_id=31337&client_secret=deadbeef&refresh_token=8xLOxBtZp8

< HTTP/1.1 200 OK
< Content-Type: application/json
<
< {
<    "access_token":"Uu8oor1i",
<    "token_type":"bearer",
<    "expires_in":86400,
<    "refresh_token":"ohWo1ohr",
< }

Описание в спецификации

Минусы OAuth 2.0

Во всей этой красоте есть и ложка дегтя, куда без нее?

OAuth 2.0 — развивающийся стандарт. Это значит, что спецификация еще не устоялась и постоянно меняется, иногда довольно заметно. Так, что если вы решили поддержать стандарт прямо сейчас, приготовьтесь к тому, что его поддержку придется подпиливать по мере изменения спецификации. С другой стороны, это также значит, что вы можете поучаствовать в процессе написания стандарта и внести в него свои идеи.

Безопасность OAuth 2.0 во многом основана на SSL. Это сильно упрощает жизнь разработчикам, но требует дополнительных вычислительных ресурсов и администрирования. Это может быть существенным вопросом в высоко нагруженных проектах.

Заключение

OAuth — простой стандарт авторизации, основанный на базовых принципах интернета, что делает возможным применение авторизации практически на любой платформе. Стандарт имеет поддержку крупнейших площадок и очевидно, что его популярность будет только расти. Если вы задумались об API для вашего сервиса, то авторизация с использованием OAuth 2.0 — хороший выбор.

Со своей стороны, мы внедрили OAuth 2.0 в API Mail.Ru и, теперь, вы можете использовать возможности протокола для реализации любых клиентов и сервисов, интегрированных с Mail.Ru.

Ссылки

• Текущая версия драфта стандарта OAuth 2.0
• Официальный сайт OAuth
• Рабочая группа по выработке стандарта (архивы)
• Документация по реализации OAuth 2.0 в Mail.Ru

Дмитрий Битман — менеджер Платформы@Mail.Ru