From 2a96807c54a534c6dfed5daf3c900a604cad87d3 Mon Sep 17 00:00:00 2001 From: Luca Degasperi Date: Wed, 11 Dec 2013 14:53:48 +0100 Subject: [PATCH] Improved documentation --- .../Repositories/FluentClient.php | 41 ++- .../OAuth2Server/Repositories/FluentScope.php | 26 ++ .../Repositories/FluentSession.php | 285 ++++++++++++++++++ 3 files changed, 351 insertions(+), 1 deletion(-) diff --git a/src/LucaDegasperi/OAuth2Server/Repositories/FluentClient.php b/src/LucaDegasperi/OAuth2Server/Repositories/FluentClient.php index 92c7983a..a4958194 100644 --- a/src/LucaDegasperi/OAuth2Server/Repositories/FluentClient.php +++ b/src/LucaDegasperi/OAuth2Server/Repositories/FluentClient.php @@ -6,7 +6,46 @@ class FluentClient implements ClientInterface { - + /** + * Validate a client + * + * Example SQL query: + * + * + * # Client ID + redirect URI + * SELECT oauth_clients.id, oauth_clients.secret, oauth_client_endpoints.redirect_uri, oauth_clients.name + * FROM oauth_clients LEFT JOIN oauth_client_endpoints ON oauth_client_endpoints.client_id = oauth_clients.id + * WHERE oauth_clients.id = :clientId AND oauth_client_endpoints.redirect_uri = :redirectUri + * + * # Client ID + client secret + * SELECT oauth_clients.id, oauth_clients.secret, oauth_clients.name FROM oauth_clients WHERE + * oauth_clients.id = :clientId AND oauth_clients.secret = :clientSecret + * + * # Client ID + client secret + redirect URI + * SELECT oauth_clients.id, oauth_clients.secret, oauth_client_endpoints.redirect_uri, oauth_clients.name FROM + * oauth_clients LEFT JOIN oauth_client_endpoints ON oauth_client_endpoints.client_id = oauth_clients.id + * WHERE oauth_clients.id = :clientId AND oauth_clients.secret = :clientSecret AND + * oauth_client_endpoints.redirect_uri = :redirectUri + * + * + * Response: + * + * + * Array + * ( + * [client_id] => (string) The client ID + * [client secret] => (string) The client secret + * [redirect_uri] => (string) The redirect URI used in this request + * [name] => (string) The name of the client + * ) + * + * + * @param string $clientId The client's ID + * @param string $clientSecret The client's secret (default = "null") + * @param string $redirectUri The client's redirect URI (default = "null") + * @param string $grantType The grant type used in the request (default = "null") + * @return bool|array Returns false if the validation fails, array on success + */ public function getClient($clientId, $clientSecret = null, $redirectUri = null, $grantType = null) { $query = null; diff --git a/src/LucaDegasperi/OAuth2Server/Repositories/FluentScope.php b/src/LucaDegasperi/OAuth2Server/Repositories/FluentScope.php index 5fe27085..68a5700e 100644 --- a/src/LucaDegasperi/OAuth2Server/Repositories/FluentScope.php +++ b/src/LucaDegasperi/OAuth2Server/Repositories/FluentScope.php @@ -7,6 +7,32 @@ class FluentScope implements ScopeInterface { + /** + * Return information about a scope + * + * Example SQL query: + * + * + * SELECT * FROM oauth_scopes WHERE scope = :scope + * + * + * Response: + * + * + * Array + * ( + * [id] => (int) The scope's ID + * [scope] => (string) The scope itself + * [name] => (string) The scope's name + * [description] => (string) The scope's description + * ) + * + * + * @param string $scope The scope + * @param string $clientId The client ID (default = "null") + * @param string $grantType The grant type used in the request (default = "null") + * @return bool|array If the scope doesn't exist return false + */ public function getScope($scope, $clientId = null, $grantType = null) { $query = DB::table('oauth_scopes') diff --git a/src/LucaDegasperi/OAuth2Server/Repositories/FluentSession.php b/src/LucaDegasperi/OAuth2Server/Repositories/FluentSession.php index 468c185e..6a44cd2d 100644 --- a/src/LucaDegasperi/OAuth2Server/Repositories/FluentSession.php +++ b/src/LucaDegasperi/OAuth2Server/Repositories/FluentSession.php @@ -7,6 +7,21 @@ class FluentSession implements SessionInterface, SessionManagementInterface { + /** + * Create a new session + * + * Example SQL query: + * + * + * INSERT INTO oauth_sessions (client_id, owner_type, owner_id) + * VALUE (:clientId, :ownerType, :ownerId) + * + * + * @param string $clientId The client ID + * @param string $ownerType The type of the session owner (e.g. "user") + * @param string $ownerId The ID of the session owner (e.g. "123") + * @return int The session ID + */ public function createSession($clientId, $ownerType, $ownerId) { return DB::table('oauth_sessions')->insertGetId(array( @@ -18,6 +33,20 @@ public function createSession($clientId, $ownerType, $ownerId) )); } + /** + * Delete a session + * + * Example SQL query: + * + * + * DELETE FROM oauth_sessions WHERE client_id = :clientId AND owner_type = :type AND owner_id = :typeId + * + * + * @param string $clientId The client ID + * @param string $ownerType The type of the session owner (e.g. "user") + * @param string $ownerId The ID of the session owner (e.g. "123") + * @return void + */ public function deleteSession($clientId, $ownerType, $ownerId) { DB::table('oauth_sessions') @@ -27,6 +56,19 @@ public function deleteSession($clientId, $ownerType, $ownerId) ->delete(); } + /** + * Associate a redirect URI with a session + * + * Example SQL query: + * + * + * INSERT INTO oauth_session_redirects (session_id, redirect_uri) VALUE (:sessionId, :redirectUri) + * + * + * @param int $sessionId The session ID + * @param string $redirectUri The redirect URI + * @return void + */ public function associateRedirectUri($sessionId, $redirectUri) { DB::table('oauth_session_redirects')->insert(array( @@ -37,6 +79,21 @@ public function associateRedirectUri($sessionId, $redirectUri) )); } + /** + * Associate an access token with a session + * + * Example SQL query: + * + * + * INSERT INTO oauth_session_access_tokens (session_id, access_token, access_token_expires) + * VALUE (:sessionId, :accessToken, :accessTokenExpire) + * + * + * @param int $sessionId The session ID + * @param string $accessToken The access token + * @param int $expireTime Unix timestamp of the access token expiry time + * @return void + */ public function associateAccessToken($sessionId, $accessToken, $expireTime) { return DB::table('oauth_session_access_tokens')->insertGetId(array( @@ -48,6 +105,22 @@ public function associateAccessToken($sessionId, $accessToken, $expireTime) )); } + /** + * Associate a refresh token with a session + * + * Example SQL query: + * + * + * INSERT INTO oauth_session_refresh_tokens (session_access_token_id, refresh_token, refresh_token_expires, + * client_id) VALUE (:accessTokenId, :refreshToken, :expireTime, :clientId) + * + * + * @param int $accessTokenId The access token ID + * @param string $refreshToken The refresh token + * @param int $expireTime Unix timestamp of the refresh token expiry time + * @param string $clientId The client ID + * @return void + */ public function associateRefreshToken($accessTokenId, $refreshToken, $expireTime, $clientId) { DB::table('oauth_session_refresh_tokens')->insert(array( @@ -60,6 +133,21 @@ public function associateRefreshToken($accessTokenId, $refreshToken, $expireTime )); } + /** + * Assocate an authorization code with a session + * + * Example SQL query: + * + * + * INSERT INTO oauth_session_authcodes (session_id, auth_code, auth_code_expires) + * VALUE (:sessionId, :authCode, :authCodeExpires) + * + * + * @param int $sessionId The session ID + * @param string $authCode The authorization code + * @param int $expireTime Unix timestamp of the access token expiry time + * @return int The auth code ID + */ public function associateAuthCode($sessionId, $authCode, $expireTime) { $id = DB::table('oauth_session_authcodes')->insertGetId(array( @@ -73,6 +161,18 @@ public function associateAuthCode($sessionId, $authCode, $expireTime) return $id; } + /** + * Remove an associated authorization token from a session + * + * Example SQL query: + * + * + * DELETE FROM oauth_session_authcodes WHERE session_id = :sessionId + * + * + * @param int $sessionId The session ID + * @return void + */ public function removeAuthCode($sessionId) { DB::table('oauth_session_authcodes') @@ -80,6 +180,34 @@ public function removeAuthCode($sessionId) ->delete(); } + /** + * Validate an authorization code + * + * Example SQL query: + * + * + * SELECT oauth_sessions.id AS session_id, oauth_session_authcodes.id AS authcode_id FROM oauth_sessions + * JOIN oauth_session_authcodes ON oauth_session_authcodes.`session_id` = oauth_sessions.id + * JOIN oauth_session_redirects ON oauth_session_redirects.`session_id` = oauth_sessions.id WHERE + * oauth_sessions.client_id = :clientId AND oauth_session_authcodes.`auth_code` = :authCode + * AND `oauth_session_authcodes`.`auth_code_expires` >= :time AND + * `oauth_session_redirects`.`redirect_uri` = :redirectUri + * + * + * Expected response: + * + * + * array( + * 'session_id' => (int) + * 'authcode_id' => (int) + * ) + * + * + * @param string $clientId The client ID + * @param string $redirectUri The redirect URI + * @param string $authCode The authorization code + * @return array|bool False if invalid or array as above + */ public function validateAuthCode($clientId, $redirectUri, $authCode) { $result = DB::table('oauth_sessions') @@ -95,6 +223,31 @@ public function validateAuthCode($clientId, $redirectUri, $authCode) return (is_null($result)) ? false : (array) $result; } + /** + * Validate an access token + * + * Example SQL query: + * + * + * SELECT session_id, oauth_sessions.`client_id`, oauth_sessions.`owner_id`, oauth_sessions.`owner_type` + * FROM `oauth_session_access_tokens` JOIN oauth_sessions ON oauth_sessions.`id` = session_id WHERE + * access_token = :accessToken AND access_token_expires >= UNIX_TIMESTAMP(NOW()) + * + * + * Expected response: + * + * + * array( + * 'session_id' => (int), + * 'client_id' => (string), + * 'owner_id' => (string), + * 'owner_type' => (string) + * ) + * + * + * @param string $accessToken The access token + * @return array|bool False if invalid or an array as above + */ public function validateAccessToken($accessToken) { $result = DB::table('oauth_session_access_tokens') @@ -110,6 +263,20 @@ public function validateAccessToken($accessToken) return (is_null($result)) ? false : (array) $result; } + /** + * Validate a refresh token + * + * Example SQL query: + * + * + * SELECT session_access_token_id FROM `oauth_session_refresh_tokens` WHERE refresh_token = :refreshToken + * AND refresh_token_expires >= UNIX_TIMESTAMP(NOW()) AND client_id = :clientId + * + * + * @param string $refreshToken The access token + * @param string $clientId The client ID + * @return int|bool The ID of the access token the refresh token is linked to (or false if invalid) + */ public function validateRefreshToken($refreshToken, $clientId) { $result = DB::table('oauth_session_refresh_tokens') @@ -121,6 +288,29 @@ public function validateRefreshToken($refreshToken, $clientId) return (is_null($result)) ? false : $result->session_access_token_id; } + /** + * Get an access token by ID + * + * Example SQL query: + * + * + * SELECT * FROM `oauth_session_access_tokens` WHERE `id` = :accessTokenId + * + * + * Expected response: + * + * + * array( + * 'id' => (int), + * 'session_id' => (int), + * 'access_token' => (string), + * 'access_token_expires' => (int) + * ) + * + * + * @param int $accessTokenId The access token ID + * @return array + */ public function getAccessToken($accessTokenId) { $result = DB::table('oauth_session_access_tokens') @@ -130,6 +320,19 @@ public function getAccessToken($accessTokenId) return (is_null($result)) ? false : (array) $result; } + /** + * Associate a scope with an access token + * + * Example SQL query: + * + * + * INSERT INTO `oauth_session_token_scopes` (`session_access_token_id`, `scope_id`) VALUE (:accessTokenId, :scopeId) + * + * + * @param int $accessTokenId The ID of the access token + * @param int $scopeId The ID of the scope + * @return void + */ public function associateScope($accessTokenId, $scopeId) { DB::table('oauth_session_token_scopes')->insert(array( @@ -140,6 +343,35 @@ public function associateScope($accessTokenId, $scopeId) )); } + /** + * Get all associated access tokens for an access token + * + * Example SQL query: + * + * + * SELECT oauth_scopes.* FROM oauth_session_token_scopes JOIN oauth_session_access_tokens + * ON oauth_session_access_tokens.`id` = `oauth_session_token_scopes`.`session_access_token_id` + * JOIN oauth_scopes ON oauth_scopes.id = `oauth_session_token_scopes`.`scope_id` + * WHERE access_token = :accessToken + * + * + * Expected response: + * + * + * array ( + * array( + * 'key' => (string), + * 'name' => (string), + * 'description' => (string) + * ), + * ... + * ... + * ) + * + * + * @param string $accessToken The access token + * @return array + */ public function getScopes($accessToken) { $scopeResults = DB::table('oauth_session_token_scopes') @@ -160,6 +392,20 @@ public function getScopes($accessToken) return $scopes; } + /** + * Associate scopes with an auth code (bound to the session) + * + * Example SQL query: + * + * + * INSERT INTO `oauth_session_authcode_scopes` (`oauth_session_authcode_id`, `scope_id`) VALUES + * (:authCodeId, :scopeId) + * + * + * @param int $authCodeId The auth code ID + * @param int $scopeId The scope ID + * @return void + */ public function associateAuthCodeScope($authCodeId, $scopeId) { DB::table('oauth_session_authcode_scopes')->insert(array( @@ -170,6 +416,32 @@ public function associateAuthCodeScope($authCodeId, $scopeId) )); } + /** + * Get the scopes associated with an auth code + * + * Example SQL query: + * + * + * SELECT scope_id FROM `oauth_session_authcode_scopes` WHERE oauth_session_authcode_id = :authCodeId + * + * + * Expected response: + * + * + * array( + * array( + * 'scope_id' => (int) + * ), + * array( + * 'scope_id' => (int) + * ), + * ... + * ) + * + * + * @param int $oauthSessionAuthCodeId The session ID + * @return array + */ public function getAuthCodeScopes($oauthSessionAuthCodeId) { $scopesResults = DB::table('oauth_session_authcode_scopes') @@ -188,6 +460,18 @@ public function getAuthCodeScopes($oauthSessionAuthCodeId) } + /** + * Removes a refresh token + * + * Example SQL query: + * + * + * DELETE FROM `oauth_session_refresh_tokens` WHERE refresh_token = :refreshToken + * + * + * @param string $refreshToken The refresh token to be removed + * @return void + */ public function removeRefreshToken($refreshToken) { DB::table('oauth_session_refresh_tokens') @@ -195,6 +479,7 @@ public function removeRefreshToken($refreshToken) ->delete(); } + public function deleteExpired() { $time = time();