add oauth2/oidc lib

15 files changed, 614 insertions, 0 deletions

diff --git a/library/oauth2/src/OAuth2/OpenID/Controller/AuthorizeController.php b/library/oauth2/src/OAuth2/OpenID/Controller/AuthorizeController.php
new file mode 100644
index 000000000..c9b5c6af7
--- /dev/null
+++ b/library/oauth2/src/OAuth2/OpenID/Controller/AuthorizeController.php
@@ -0,0 +1,106 @@
+<?php
+
+namespace OAuth2\OpenID\Controller;
+
+use OAuth2\Controller\AuthorizeController as BaseAuthorizeController;
+use OAuth2\RequestInterface;
+use OAuth2\ResponseInterface;
+
+/**
+ * @see OAuth2\Controller\AuthorizeControllerInterface
+ */
+class AuthorizeController extends BaseAuthorizeController implements AuthorizeControllerInterface
+{
+    private $nonce;
+
+    protected function setNotAuthorizedResponse(RequestInterface $request, ResponseInterface $response, $redirect_uri, $user_id = null)
+    {
+        $prompt = $request->query('prompt', 'consent');
+        if ($prompt == 'none') {
+            if (is_null($user_id)) {
+                $error = 'login_required';
+                $error_message = 'The user must log in';
+            } else {
+                $error = 'interaction_required';
+                $error_message = 'The user must grant access to your application';
+            }
+        } else {
+            $error = 'consent_required';
+            $error_message = 'The user denied access to your application';
+        }
+
+        $response->setRedirect($this->config['redirect_status_code'], $redirect_uri, $this->getState(), $error, $error_message);
+    }
+
+    protected function buildAuthorizeParameters($request, $response, $user_id)
+    {
+        if (!$params = parent::buildAuthorizeParameters($request, $response, $user_id)) {
+            return;
+        }
+
+        // Generate an id token if needed.
+        if ($this->needsIdToken($this->getScope()) && $this->getResponseType() == self::RESPONSE_TYPE_AUTHORIZATION_CODE) {
+            $params['id_token'] = $this->responseTypes['id_token']->createIdToken($this->getClientId(), $user_id, $this->nonce);
+        }
+
+        // add the nonce to return with the redirect URI
+        $params['nonce'] = $this->nonce;
+
+        return $params;
+    }
+
+    public function validateAuthorizeRequest(RequestInterface $request, ResponseInterface $response)
+    {
+        if (!parent::validateAuthorizeRequest($request, $response)) {
+            return false;
+        }
+
+        $nonce = $request->query('nonce');
+
+        // Validate required nonce for "id_token" and "id_token token"
+        if (!$nonce && in_array($this->getResponseType(), array(self::RESPONSE_TYPE_ID_TOKEN, self::RESPONSE_TYPE_ID_TOKEN_TOKEN))) {
+            $response->setError(400, 'invalid_nonce', 'This application requires you specify a nonce parameter');
+
+            return false;
+        }
+
+        $this->nonce = $nonce;
+
+        return true;
+    }
+
+    protected function getValidResponseTypes()
+    {
+        return array(
+            self::RESPONSE_TYPE_ACCESS_TOKEN,
+            self::RESPONSE_TYPE_AUTHORIZATION_CODE,
+            self::RESPONSE_TYPE_ID_TOKEN,
+            self::RESPONSE_TYPE_ID_TOKEN_TOKEN,
+            self::RESPONSE_TYPE_CODE_ID_TOKEN,
+        );
+    }
+
+    /**
+     * Returns whether the current request needs to generate an id token.
+     *
+     * ID Tokens are a part of the OpenID Connect specification, so this
+     * method checks whether OpenID Connect is enabled in the server settings
+     * and whether the openid scope was requested.
+     *
+     * @param $request_scope
+     *  A space-separated string of scopes.
+     *
+     * @return
+     *   TRUE if an id token is needed, FALSE otherwise.
+     */
+    public function needsIdToken($request_scope)
+    {
+        // see if the "openid" scope exists in the requested scope
+        return $this->scopeUtil->checkScope('openid', $request_scope);
+    }
+
+    public function getNonce()
+    {
+        return $this->nonce;
+    }
+}
diff --git a/library/oauth2/src/OAuth2/OpenID/Controller/AuthorizeControllerInterface.php b/library/oauth2/src/OAuth2/OpenID/Controller/AuthorizeControllerInterface.php
new file mode 100644
index 000000000..1e231d844
--- /dev/null
+++ b/library/oauth2/src/OAuth2/OpenID/Controller/AuthorizeControllerInterface.php
@@ -0,0 +1,10 @@
+<?php
+
+namespace OAuth2\OpenID\Controller;
+
+interface AuthorizeControllerInterface
+{
+    const RESPONSE_TYPE_ID_TOKEN = 'id_token';
+    const RESPONSE_TYPE_ID_TOKEN_TOKEN = 'id_token token';
+    const RESPONSE_TYPE_CODE_ID_TOKEN  = 'code id_token';
+}
diff --git a/library/oauth2/src/OAuth2/OpenID/Controller/UserInfoController.php b/library/oauth2/src/OAuth2/OpenID/Controller/UserInfoController.php
new file mode 100644
index 000000000..30cb942d0
--- /dev/null
+++ b/library/oauth2/src/OAuth2/OpenID/Controller/UserInfoController.php
@@ -0,0 +1,58 @@
+<?php
+
+namespace OAuth2\OpenID\Controller;
+
+use OAuth2\Scope;
+use OAuth2\TokenType\TokenTypeInterface;
+use OAuth2\Storage\AccessTokenInterface;
+use OAuth2\OpenID\Storage\UserClaimsInterface;
+use OAuth2\Controller\ResourceController;
+use OAuth2\ScopeInterface;
+use OAuth2\RequestInterface;
+use OAuth2\ResponseInterface;
+
+/**
+ * @see OAuth2\Controller\UserInfoControllerInterface
+ */
+class UserInfoController extends ResourceController implements UserInfoControllerInterface
+{
+    private $token;
+
+    protected $tokenType;
+    protected $tokenStorage;
+    protected $userClaimsStorage;
+    protected $config;
+    protected $scopeUtil;
+
+    public function __construct(TokenTypeInterface $tokenType, AccessTokenInterface $tokenStorage, UserClaimsInterface $userClaimsStorage, $config = array(), ScopeInterface $scopeUtil = null)
+    {
+        $this->tokenType = $tokenType;
+        $this->tokenStorage = $tokenStorage;
+        $this->userClaimsStorage = $userClaimsStorage;
+
+        $this->config = array_merge(array(
+            'www_realm' => 'Service',
+        ), $config);
+
+        if (is_null($scopeUtil)) {
+            $scopeUtil = new Scope();
+        }
+        $this->scopeUtil = $scopeUtil;
+    }
+
+    public function handleUserInfoRequest(RequestInterface $request, ResponseInterface $response)
+    {
+        if (!$this->verifyResourceRequest($request, $response, 'openid')) {
+            return;
+        }
+
+        $token = $this->getToken();
+        $claims = $this->userClaimsStorage->getUserClaims($token['user_id'], $token['scope']);
+        // The sub Claim MUST always be returned in the UserInfo Response.
+        // http://openid.net/specs/openid-connect-core-1_0.html#UserInfoResponse
+        $claims += array(
+            'sub' => $token['user_id'],
+        );
+        $response->addParameters($claims);
+    }
+}
diff --git a/library/oauth2/src/OAuth2/OpenID/Controller/UserInfoControllerInterface.php b/library/oauth2/src/OAuth2/OpenID/Controller/UserInfoControllerInterface.php
new file mode 100644
index 000000000..a89049d49
--- /dev/null
+++ b/library/oauth2/src/OAuth2/OpenID/Controller/UserInfoControllerInterface.php
@@ -0,0 +1,23 @@
+<?php
+
+namespace OAuth2\OpenID\Controller;
+
+use OAuth2\RequestInterface;
+use OAuth2\ResponseInterface;
+
+/**
+ *  This controller is called when the user claims for OpenID Connect's
+ *  UserInfo endpoint should be returned.
+ *
+ *  ex:
+ *  > $response = new OAuth2\Response();
+ *  > $userInfoController->handleUserInfoRequest(
+ *  >     OAuth2\Request::createFromGlobals(),
+ *  >     $response;
+ *  > $response->send();
+ *
+ */
+interface UserInfoControllerInterface
+{
+    public function handleUserInfoRequest(RequestInterface $request, ResponseInterface $response);
+}
diff --git a/library/oauth2/src/OAuth2/OpenID/GrantType/AuthorizationCode.php b/library/oauth2/src/OAuth2/OpenID/GrantType/AuthorizationCode.php
new file mode 100644
index 000000000..8ed1edc26
--- /dev/null
+++ b/library/oauth2/src/OAuth2/OpenID/GrantType/AuthorizationCode.php
@@ -0,0 +1,33 @@
+<?php
+
+namespace OAuth2\OpenID\GrantType;
+
+use OAuth2\GrantType\AuthorizationCode as BaseAuthorizationCode;
+use OAuth2\ResponseType\AccessTokenInterface;
+
+/**
+ *
+ * @author Brent Shaffer <bshafs at gmail dot com>
+ */
+class AuthorizationCode extends BaseAuthorizationCode
+{
+    public function createAccessToken(AccessTokenInterface $accessToken, $client_id, $user_id, $scope)
+    {
+        $includeRefreshToken = true;
+        if (isset($this->authCode['id_token'])) {
+            // OpenID Connect requests include the refresh token only if the
+            // offline_access scope has been requested and granted.
+            $scopes = explode(' ', trim($scope));
+            $includeRefreshToken = in_array('offline_access', $scopes);
+        }
+
+        $token = $accessToken->createAccessToken($client_id, $user_id, $scope, $includeRefreshToken);
+        if (isset($this->authCode['id_token'])) {
+            $token['id_token'] = $this->authCode['id_token'];
+        }
+
+        $this->storage->expireAuthorizationCode($this->authCode['code']);
+
+        return $token;
+    }
+}
diff --git a/library/oauth2/src/OAuth2/OpenID/ResponseType/AuthorizationCode.php b/library/oauth2/src/OAuth2/OpenID/ResponseType/AuthorizationCode.php
new file mode 100644
index 000000000..8971954c5
--- /dev/null
+++ b/library/oauth2/src/OAuth2/OpenID/ResponseType/AuthorizationCode.php
@@ -0,0 +1,60 @@
+<?php
+
+namespace OAuth2\OpenID\ResponseType;
+
+use OAuth2\ResponseType\AuthorizationCode as BaseAuthorizationCode;
+use OAuth2\OpenID\Storage\AuthorizationCodeInterface as AuthorizationCodeStorageInterface;
+
+/**
+ *
+ * @author Brent Shaffer <bshafs at gmail dot com>
+ */
+class AuthorizationCode extends BaseAuthorizationCode implements AuthorizationCodeInterface
+{
+    public function __construct(AuthorizationCodeStorageInterface $storage, array $config = array())
+    {
+        parent::__construct($storage, $config);
+    }
+
+    public function getAuthorizeResponse($params, $user_id = null)
+    {
+        // build the URL to redirect to
+        $result = array('query' => array());
+
+        $params += array('scope' => null, 'state' => null, 'id_token' => null);
+
+        $result['query']['code'] = $this->createAuthorizationCode($params['client_id'], $user_id, $params['redirect_uri'], $params['scope'], $params['id_token']);
+
+        if (isset($params['state'])) {
+            $result['query']['state'] = $params['state'];
+        }
+
+        return array($params['redirect_uri'], $result);
+    }
+
+    /**
+     * Handle the creation of the authorization code.
+     *
+     * @param $client_id
+     * Client identifier related to the authorization code
+     * @param $user_id
+     * User ID associated with the authorization code
+     * @param $redirect_uri
+     * An absolute URI to which the authorization server will redirect the
+     * user-agent to when the end-user authorization step is completed.
+     * @param $scope
+     * (optional) Scopes to be stored in space-separated string.
+     * @param $id_token
+     * (optional) The OpenID Connect id_token.
+     *
+     * @see http://tools.ietf.org/html/rfc6749#section-4
+     * @ingroup oauth2_section_4
+     */
+    public function createAuthorizationCode($client_id, $user_id, $redirect_uri, $scope = null, $id_token = null)
+    {
+        $code = $this->generateAuthorizationCode();
+        $this->storage->setAuthorizationCode($code, $client_id, $user_id, $redirect_uri, time() + $this->config['auth_code_lifetime'], $scope, $id_token);
+
+        return $code;
+    }
+}
diff --git a/library/oauth2/src/OAuth2/OpenID/ResponseType/AuthorizationCodeInterface.php b/library/oauth2/src/OAuth2/OpenID/ResponseType/AuthorizationCodeInterface.php
new file mode 100644
index 000000000..ea4779255
--- /dev/null
+++ b/library/oauth2/src/OAuth2/OpenID/ResponseType/AuthorizationCodeInterface.php
@@ -0,0 +1,27 @@
+<?php
+
+namespace OAuth2\OpenID\ResponseType;
+
+use OAuth2\ResponseType\AuthorizationCodeInterface as BaseAuthorizationCodeInterface;
+
+/**
+ *
+ * @author Brent Shaffer <bshafs at gmail dot com>
+ */
+interface AuthorizationCodeInterface extends BaseAuthorizationCodeInterface
+{
+    /**
+     * Handle the creation of the authorization code.
+     *
+     * @param $client_id                Client identifier related to the authorization code
+     * @param $user_id                  User ID associated with the authorization code
+     * @param $redirect_uri             An absolute URI to which the authorization server will redirect the
+     *                                  user-agent to when the end-user authorization step is completed.
+     * @param $scope        OPTIONAL    Scopes to be stored in space-separated string.
+     * @param $id_token     OPTIONAL    The OpenID Connect id_token.
+     *
+     * @see http://tools.ietf.org/html/rfc6749#section-4
+     * @ingroup oauth2_section_4
+     */
+    public function createAuthorizationCode($client_id, $user_id, $redirect_uri, $scope = null, $id_token = null);
+}
diff --git a/library/oauth2/src/OAuth2/OpenID/ResponseType/CodeIdToken.php b/library/oauth2/src/OAuth2/OpenID/ResponseType/CodeIdToken.php
new file mode 100644
index 000000000..ac7764d6c
--- /dev/null
+++ b/library/oauth2/src/OAuth2/OpenID/ResponseType/CodeIdToken.php
@@ -0,0 +1,24 @@
+<?php
+
+namespace OAuth2\OpenID\ResponseType;
+
+class CodeIdToken implements CodeIdTokenInterface
+{
+    protected $authCode;
+    protected $idToken;
+
+    public function __construct(AuthorizationCodeInterface $authCode, IdTokenInterface $idToken)
+    {
+        $this->authCode = $authCode;
+        $this->idToken = $idToken;
+    }
+
+    public function getAuthorizeResponse($params, $user_id = null)
+    {
+        $result = $this->authCode->getAuthorizeResponse($params, $user_id);
+        $resultIdToken = $this->idToken->getAuthorizeResponse($params, $user_id);
+        $result[1]['query']['id_token'] = $resultIdToken[1]['fragment']['id_token'];
+
+        return $result;
+    }
+}
diff --git a/library/oauth2/src/OAuth2/OpenID/ResponseType/CodeIdTokenInterface.php b/library/oauth2/src/OAuth2/OpenID/ResponseType/CodeIdTokenInterface.php
new file mode 100644
index 000000000..629adcca8
--- /dev/null
+++ b/library/oauth2/src/OAuth2/OpenID/ResponseType/CodeIdTokenInterface.php
@@ -0,0 +1,9 @@
+<?php
+
+namespace OAuth2\OpenID\ResponseType;
+
+use OAuth2\ResponseType\ResponseTypeInterface;
+
+interface CodeIdTokenInterface extends ResponseTypeInterface
+{
+}
diff --git a/library/oauth2/src/OAuth2/OpenID/ResponseType/IdToken.php b/library/oauth2/src/OAuth2/OpenID/ResponseType/IdToken.php
new file mode 100644
index 000000000..97777fbf2
--- /dev/null
+++ b/library/oauth2/src/OAuth2/OpenID/ResponseType/IdToken.php
@@ -0,0 +1,124 @@
+<?php
+
+namespace OAuth2\OpenID\ResponseType;
+
+use OAuth2\Encryption\EncryptionInterface;
+use OAuth2\Encryption\Jwt;
+use OAuth2\Storage\PublicKeyInterface;
+use OAuth2\OpenID\Storage\UserClaimsInterface;
+
+class IdToken implements IdTokenInterface
+{
+    protected $userClaimsStorage;
+    protected $publicKeyStorage;
+    protected $config;
+    protected $encryptionUtil;
+
+    public function __construct(UserClaimsInterface $userClaimsStorage, PublicKeyInterface $publicKeyStorage, array $config = array(), EncryptionInterface $encryptionUtil = null)
+    {
+        $this->userClaimsStorage = $userClaimsStorage;
+        $this->publicKeyStorage = $publicKeyStorage;
+        if (is_null($encryptionUtil)) {
+            $encryptionUtil = new Jwt();
+        }
+        $this->encryptionUtil = $encryptionUtil;
+
+        if (!isset($config['issuer'])) {
+            throw new \LogicException('config parameter "issuer" must be set');
+        }
+        $this->config = array_merge(array(
+            'id_lifetime' => 3600,
+        ), $config);
+    }
+
+    public function getAuthorizeResponse($params, $userInfo = null)
+    {
+        // build the URL to redirect to
+        $result = array('query' => array());
+        $params += array('scope' => null, 'state' => null, 'nonce' => null);
+
+        // create the id token.
+        list($user_id, $auth_time) = $this->getUserIdAndAuthTime($userInfo);
+        $userClaims = $this->userClaimsStorage->getUserClaims($user_id, $params['scope']);
+
+        $id_token = $this->createIdToken($params['client_id'], $userInfo, $params['nonce'], $userClaims, null);
+        $result["fragment"] = array('id_token' => $id_token);
+        if (isset($params['state'])) {
+            $result["fragment"]["state"] = $params['state'];
+        }
+
+        return array($params['redirect_uri'], $result);
+    }
+
+    public function createIdToken($client_id, $userInfo, $nonce = null, $userClaims = null, $access_token = null)
+    {
+        // pull auth_time from user info if supplied
+        list($user_id, $auth_time) = $this->getUserIdAndAuthTime($userInfo);
+
+        $token = array(
+            'iss'        => $this->config['issuer'],
+            'sub'        => $user_id,
+            'aud'        => $client_id,
+            'iat'        => time(),
+            'exp'        => time() + $this->config['id_lifetime'],
+            'auth_time'  => $auth_time,
+        );
+
+        if ($nonce) {
+            $token['nonce'] = $nonce;
+        }
+
+        if ($userClaims) {
+            $token += $userClaims;
+        }
+
+        if ($access_token) {
+            $token['at_hash'] = $this->createAtHash($access_token, $client_id);
+        }
+
+        return $this->encodeToken($token, $client_id);
+    }
+
+    protected function createAtHash($access_token, $client_id = null)
+    {
+        // maps HS256 and RS256 to sha256, etc.
+        $algorithm = $this->publicKeyStorage->getEncryptionAlgorithm($client_id);
+        $hash_algorithm = 'sha' . substr($algorithm, 2);
+        $hash = hash($hash_algorithm, $access_token, true);
+        $at_hash = substr($hash, 0, strlen($hash) / 2);
+
+        return $this->encryptionUtil->urlSafeB64Encode($at_hash);
+    }
+
+    protected function encodeToken(array $token, $client_id = null)
+    {
+        $private_key = $this->publicKeyStorage->getPrivateKey($client_id);
+        $algorithm = $this->publicKeyStorage->getEncryptionAlgorithm($client_id);
+
+        return $this->encryptionUtil->encode($token, $private_key, $algorithm);
+    }
+
+    private function getUserIdAndAuthTime($userInfo)
+    {
+        $auth_time = null;
+
+        // support an array for user_id / auth_time
+        if (is_array($userInfo)) {
+            if (!isset($userInfo['user_id'])) {
+                throw new \LogicException('if $user_id argument is an array, user_id index must be set');
+            }
+
+            $auth_time = isset($userInfo['auth_time']) ? $userInfo['auth_time'] : null;
+            $user_id = $userInfo['user_id'];
+        } else {
+            $user_id = $userInfo;
+        }
+
+        if (is_null($auth_time)) {
+            $auth_time = time();
+        }
+
+        // userInfo is a scalar, and so this is the $user_id. Auth Time is null
+        return array($user_id, $auth_time);
+    }
+}
diff --git a/library/oauth2/src/OAuth2/OpenID/ResponseType/IdTokenInterface.php b/library/oauth2/src/OAuth2/OpenID/ResponseType/IdTokenInterface.php
new file mode 100644
index 000000000..0bd2f8391
--- /dev/null
+++ b/library/oauth2/src/OAuth2/OpenID/ResponseType/IdTokenInterface.php
@@ -0,0 +1,29 @@
+<?php
+
+namespace OAuth2\OpenID\ResponseType;
+
+use OAuth2\ResponseType\ResponseTypeInterface;
+
+interface IdTokenInterface extends ResponseTypeInterface
+{
+    /**
+     * Create the id token.
+     *
+     * If Authorization Code Flow is used, the id_token is generated when the
+     * authorization code is issued, and later returned from the token endpoint
+     * together with the access_token.
+     * If the Implicit Flow is used, the token and id_token are generated and
+     * returned together.
+     *
+     * @param string $client_id    The client id.
+     * @param string $user_id      The user id.
+     * @param string $nonce        OPTIONAL The nonce.
+     * @param string $userClaims   OPTIONAL Claims about the user.
+     * @param string $access_token OPTIONAL The access token, if known.
+     *
+     * @return string The ID Token represented as a JSON Web Token (JWT).
+     *
+     * @see http://openid.net/specs/openid-connect-core-1_0.html#IDToken
+     */
+    public function createIdToken($client_id, $userInfo, $nonce = null, $userClaims = null, $access_token = null);
+}
diff --git a/library/oauth2/src/OAuth2/OpenID/ResponseType/IdTokenToken.php b/library/oauth2/src/OAuth2/OpenID/ResponseType/IdTokenToken.php
new file mode 100644
index 000000000..f0c59799b
--- /dev/null
+++ b/library/oauth2/src/OAuth2/OpenID/ResponseType/IdTokenToken.php
@@ -0,0 +1,27 @@
+<?php
+
+namespace OAuth2\OpenID\ResponseType;
+
+use OAuth2\ResponseType\AccessTokenInterface;
+
+class IdTokenToken implements IdTokenTokenInterface
+{
+    protected $accessToken;
+    protected $idToken;
+
+    public function __construct(AccessTokenInterface $accessToken, IdTokenInterface $idToken)
+    {
+        $this->accessToken = $accessToken;
+        $this->idToken = $idToken;
+    }
+
+    public function getAuthorizeResponse($params, $user_id = null)
+    {
+        $result = $this->accessToken->getAuthorizeResponse($params, $user_id);
+        $access_token = $result[1]['fragment']['access_token'];
+        $id_token = $this->idToken->createIdToken($params['client_id'], $user_id, $params['nonce'], null, $access_token);
+        $result[1]['fragment']['id_token'] = $id_token;
+
+        return $result;
+    }
+}
diff --git a/library/oauth2/src/OAuth2/OpenID/ResponseType/IdTokenTokenInterface.php b/library/oauth2/src/OAuth2/OpenID/ResponseType/IdTokenTokenInterface.php
new file mode 100644
index 000000000..ac13e2032
--- /dev/null
+++ b/library/oauth2/src/OAuth2/OpenID/ResponseType/IdTokenTokenInterface.php
@@ -0,0 +1,9 @@
+<?php
+
+namespace OAuth2\OpenID\ResponseType;
+
+use OAuth2\ResponseType\ResponseTypeInterface;
+
+interface IdTokenTokenInterface extends ResponseTypeInterface
+{
+}
diff --git a/library/oauth2/src/OAuth2/OpenID/Storage/AuthorizationCodeInterface.php b/library/oauth2/src/OAuth2/OpenID/Storage/AuthorizationCodeInterface.php
new file mode 100644
index 000000000..51dd867ec
--- /dev/null
+++ b/library/oauth2/src/OAuth2/OpenID/Storage/AuthorizationCodeInterface.php
@@ -0,0 +1,37 @@
+<?php
+
+namespace OAuth2\OpenID\Storage;
+
+use OAuth2\Storage\AuthorizationCodeInterface as BaseAuthorizationCodeInterface;
+/**
+ * Implement this interface to specify where the OAuth2 Server
+ * should get/save authorization codes for the "Authorization Code"
+ * grant type
+ *
+ * @author Brent Shaffer <bshafs at gmail dot com>
+ */
+interface AuthorizationCodeInterface extends BaseAuthorizationCodeInterface
+{
+    /**
+     * Take the provided authorization code values and store them somewhere.
+     *
+     * This function should be the storage counterpart to getAuthCode().
+     *
+     * If storage fails for some reason, we're not currently checking for
+     * any sort of success/failure, so you should bail out of the script
+     * and provide a descriptive fail message.
+     *
+     * Required for OAuth2::GRANT_TYPE_AUTH_CODE.
+     *
+     * @param $code                authorization code to be stored.
+     * @param $client_id           client identifier to be stored.
+     * @param $user_id             user identifier to be stored.
+     * @param string $redirect_uri redirect URI(s) to be stored in a space-separated string.
+     * @param int    $expires      expiration to be stored as a Unix timestamp.
+     * @param string $scope        OPTIONAL scopes to be stored in space-separated string.
+     * @param string $id_token     OPTIONAL the OpenID Connect id_token.
+     *
+     * @ingroup oauth2_section_4
+     */
+    public function setAuthorizationCode($code, $client_id, $user_id, $redirect_uri, $expires, $scope = null, $id_token = null);
+}
diff --git a/library/oauth2/src/OAuth2/OpenID/Storage/UserClaimsInterface.php b/library/oauth2/src/OAuth2/OpenID/Storage/UserClaimsInterface.php
new file mode 100644
index 000000000..f230bef9e
--- /dev/null
+++ b/library/oauth2/src/OAuth2/OpenID/Storage/UserClaimsInterface.php
@@ -0,0 +1,38 @@
+<?php
+
+namespace OAuth2\OpenID\Storage;
+
+/**
+ * Implement this interface to specify where the OAuth2 Server
+ * should retrieve user claims for the OpenID Connect id_token.
+ */
+interface UserClaimsInterface
+{
+    // valid scope values to pass into the user claims API call
+    const VALID_CLAIMS = 'profile email address phone';
+
+    // fields returned for the claims above
+    const PROFILE_CLAIM_VALUES  = 'name family_name given_name middle_name nickname preferred_username profile picture website gender birthdate zoneinfo locale updated_at';
+    const EMAIL_CLAIM_VALUES    = 'email email_verified';
+    const ADDRESS_CLAIM_VALUES  = 'formatted street_address locality region postal_code country';
+    const PHONE_CLAIM_VALUES    = 'phone_number phone_number_verified';
+
+    /**
+     * Return claims about the provided user id.
+     *
+     * Groups of claims are returned based on the requested scopes. No group
+     * is required, and no claim is required.
+     *
+     * @param $user_id
+     * The id of the user for which claims should be returned.
+     * @param $scope
+     * The requested scope.
+     * Scopes with matching claims: profile, email, address, phone.
+     *
+     * @return
+     * An array in the claim => value format.
+     *
+     * @see http://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims
+     */
+    public function getUserClaims($user_id, $scope);
+}