From 0e96a35f43d10d0631e0dea5995234198a4c2b7a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juli=C3=A1n=20Guti=C3=A9rrez?= Date: Tue, 29 Mar 2016 10:05:49 +0200 Subject: [PATCH] documentation for PR #502 --- auth-server-auth-code.md | 20 +++++++++++--------- auth-server-client-credentials.md | 18 ++++++++++-------- auth-server-implicit.md | 24 +++++++++++++----------- auth-server-password.md | 20 +++++++++++--------- auth-server-refresh-token.md | 20 +++++++++++--------- installation.md | 24 +++++++++++++++++++----- 6 files changed, 75 insertions(+), 51 deletions(-) diff --git a/auth-server-auth-code.md b/auth-server-auth-code.md index b6faa5a2..13120c08 100755 --- a/auth-server-auth-code.md +++ b/auth-server-auth-code.md @@ -60,16 +60,18 @@ $refreshTokenRepository = new RefreshTokenRepository(); $userRepository = new UserRepository(); // Path to public and private keys -$privateKeyPath = 'file://path/to/private.key'; -$publicKeyPath = 'file://path/to/public.key'; - +$privateKey = 'file://path/to/private.key'; +// Private key with passphrase if needed +//$privateKey = new CryptKey('file://path/to/private.key', 'passphrase'); +$publicKey = 'file://path/to/public.key'; + // Setup the authorization server $server = new \League\OAuth2\Server\Server( $clientRepository, $accessTokenRepository, $scopeRepository, - $privateKeyPath, - $publicKeyPath + $privateKey, + $publicKey ); // Enable the authentication code grant on the server with a token TTL of 1 hour @@ -94,13 +96,13 @@ $app->post('/oauth2', function (ServerRequestInterface $request, ResponseInterfa /* @var \League\OAuth2\Server\Server $server */ $server = $app->getContainer()->get(Server::class); - // Try to respond to the request + // Try to respond to the request try { return $server->respondToRequest($request, $response); - + } catch (\League\OAuth2\Server\Exception\OAuthServerException $exception) { return $exception->generateHttpResponse($response); - + } catch (\Exception $exception) { $body = new Stream('php://temp', 'r+'); $body->write($exception->getMessage()); @@ -170,4 +172,4 @@ $renderer = new \League\OAuth2\Server\TemplateRenderer\MustacheRenderer( 'authorize_template_name' ); $authCodeGrant->setTemplateRenderer($renderer); -{% endhighlight %} \ No newline at end of file +{% endhighlight %} diff --git a/auth-server-client-credentials.md b/auth-server-client-credentials.md index 111de611..83f12022 100755 --- a/auth-server-client-credentials.md +++ b/auth-server-client-credentials.md @@ -34,16 +34,18 @@ $accessTokenRepository = new AccessTokenRepository(); $scopeRepository = new ScopeRepository(); // Path to public and private keys -$privateKeyPath = 'file://path/to/private.key'; -$publicKeyPath = 'file://path/to/public.key'; - +$privateKey = 'file://path/to/private.key'; +// Private key with passphrase if needed +//$privateKey = new CryptKey('file://path/to/private.key', 'passphrase'); +$publicKey = 'file://path/to/public.key'; + // Setup the authorization server $server = new \League\OAuth2\Server\Server( $clientRepository, $accessTokenRepository, $scopeRepository, - $privateKeyPath, - $publicKeyPath + $privateKey, + $publicKey ); // Enable the client credentials grant on the server with a token TTL of 1 hour @@ -63,13 +65,13 @@ $app->post('/access_token', function (ServerRequestInterface $request, ResponseI /* @var \League\OAuth2\Server\Server $server */ $server = $app->getContainer()->get(Server::class); - // Try to respond to the request + // Try to respond to the request try { return $server->respondToRequest($request, $response); - + } catch (\League\OAuth2\Server\Exception\OAuthServerException $exception) { return $exception->generateHttpResponse($response); - + } catch (\Exception $exception) { $body = new Stream('php://temp', 'r+'); $body->write($exception->getMessage()); diff --git a/auth-server-implicit.md b/auth-server-implicit.md index 32931e00..9b22dc5c 100755 --- a/auth-server-implicit.md +++ b/auth-server-implicit.md @@ -6,14 +6,14 @@ permalink: /authorization-server/implicit-grant/ # Implicit grant -The implicit grant is similar to the authorization code grant with two distinct differences. +The implicit grant is similar to the authorization code grant with two distinct differences. It is intended to be used for user-agent-based clients (e.g. single page web apps) that can't keep a client secret because all of the application code and storage is easily accessible. Secondly instead of the authorization server returning an authorization code which is exchanged for an access token, the authorization server returns an access token. ## Flow - + The client will redirect the user to the authorization server with the following parameters in the query string: * `response_type` with the value `token` @@ -46,16 +46,18 @@ $accessTokenRepository = new AccessTokenRepository(); $userRepository = new UserRepository(); // Path to public and private keys -$privateKeyPath = 'file://path/to/private.key'; -$publicKeyPath = 'file://path/to/public.key'; - +$privateKey = 'file://path/to/private.key'; +// Private key with passphrase if needed +//$privateKey = new CryptKey('file://path/to/private.key', 'passphrase'); +$publicKey = 'file://path/to/public.key'; + // Setup the authorization server $server = new \League\OAuth2\Server\Server( $clientRepository, $accessTokenRepository, $scopeRepository, - $privateKeyPath, - $publicKeyPath + $privateKey, + $publicKey ); // Enable the implicit grant on the server with a token TTL of 1 hour @@ -75,13 +77,13 @@ $app->post('/oauth2', function (ServerRequestInterface $request, ResponseInterfa /* @var \League\OAuth2\Server\Server $server */ $server = $app->getContainer()->get(Server::class); - // Try to respond to the request + // Try to respond to the request try { return $server->respondToRequest($request, $response); - + } catch (\League\OAuth2\Server\Exception\OAuthServerException $exception) { return $exception->generateHttpResponse($response); - + } catch (\Exception $exception) { $body = new Stream('php://temp', 'r+'); $body->write($exception->getMessage()); @@ -151,4 +153,4 @@ $renderer = new \League\OAuth2\Server\TemplateRenderer\MustacheRenderer( 'authorize_template_name' ); $implicitGrant->setTemplateRenderer($renderer); -{% endhighlight %} \ No newline at end of file +{% endhighlight %} diff --git a/auth-server-password.md b/auth-server-password.md index 38951f6f..72635041 100755 --- a/auth-server-password.md +++ b/auth-server-password.md @@ -41,22 +41,24 @@ $userRepository = new UserRepository(); $refreshTokenRepository = new RefreshTokenRepository(); // Path to public and private keys -$privateKeyPath = 'file://path/to/private.key'; -$publicKeyPath = 'file://path/to/public.key'; - +$privateKey = 'file://path/to/private.key'; +// Private key with passphrase if needed +//$privateKey = new CryptKey('file://path/to/private.key', 'passphrase'); +$publicKey = 'file://path/to/public.key'; + // Setup the authorization server $server = new \League\OAuth2\Server\Server( $clientRepository, $accessTokenRepository, $scopeRepository, - $privateKeyPath, - $publicKeyPath + $privateKey, + $publicKey ); // Enable the password grant on the server with an access token TTL of 1 hour $server->enableGrantType( new \League\OAuth2\Server\Grant\PasswordGrant( - $userRepository, + $userRepository, $refreshTokenRepository ), new \DateInterval('PT1H') @@ -73,13 +75,13 @@ $app->post('/access_token', function (ServerRequestInterface $request, ResponseI /* @var \League\OAuth2\Server\Server $server */ $server = $app->getContainer()->get(Server::class); - // Try to respond to the request + // Try to respond to the request try { return $server->respondToRequest($request, $response); - + } catch (\League\OAuth2\Server\Exception\OAuthServerException $exception) { return $exception->generateHttpResponse($response); - + } catch (\Exception $exception) { $body = new Stream('php://temp', 'r+'); $body->write($exception->getMessage()); diff --git a/auth-server-refresh-token.md b/auth-server-refresh-token.md index 12438104..cac3778f 100755 --- a/auth-server-refresh-token.md +++ b/auth-server-refresh-token.md @@ -15,7 +15,7 @@ The client sends a POST request with following body parameters to the authorizat * `grant_type` with the value `refresh_token` * `client_id` with the the client's ID * `client_secret` with the client's secret -* `scope` with a space-delimited list of requested scope permissions. This is optional; if not sent the original scopes will be used, otherwise you can request a reduced set of scopes. +* `scope` with a space-delimited list of requested scope permissions. This is optional; if not sent the original scopes will be used, otherwise you can request a reduced set of scopes. The authorization server will respond with a JSON object containing the following properties: @@ -36,16 +36,18 @@ $scopeRepository = new ScopeRepository(); $refreshTokenRepository = new RefreshTokenRepository(); // Path to public and private keys -$privateKeyPath = 'file://path/to/private.key'; -$publicKeyPath = 'file://path/to/public.key'; - +$privateKey = 'file://path/to/private.key'; +// Private key with passphrase if needed +//$privateKey = new CryptKey('file://path/to/private.key', 'passphrase'); +$publicKey = 'file://path/to/public.key'; + // Setup the authorization server $server = new \League\OAuth2\Server\Server( $clientRepository, $accessTokenRepository, $scopeRepository, - $privateKeyPath, - $publicKeyPath + $privateKey, + $publicKey ); // Enable the refresh token grant on the server with a token TTL of 1 hour @@ -65,13 +67,13 @@ $app->post('/access_token', function (ServerRequestInterface $request, ResponseI /* @var \League\OAuth2\Server\Server $server */ $server = $app->getContainer()->get(Server::class); - // Try to respond to the request + // Try to respond to the request try { return $server->respondToRequest($request, $response); - + } catch (\League\OAuth2\Server\Exception\OAuthServerException $exception) { return $exception->generateHttpResponse($response); - + } catch (\Exception $exception) { $body = new Stream('php://temp', 'r+'); $body->write($exception->getMessage()); diff --git a/installation.md b/installation.md index 34446b43..0ec92424 100755 --- a/installation.md +++ b/installation.md @@ -18,12 +18,12 @@ The following versions of PHP are supported: In your project root just run: {% highlight shell %} -$ $ composer require league/oauth2-server:5.0.0-RC1 +composer require league/oauth2-server:5.0.0-RC1 {% endhighlight %} Ensure that you’ve set up your project to [autoload Composer-installed packages](https://getcomposer.org/doc/00-intro.md#autoloading). -Depending on [which grant](/authorization-server/which-grant/) you are implementing you will need to implement a number of repository interfaces. Each grant documentation page lists which repositories are required, and each repository interface has it's own documentation page. +Depending on [which grant](/authorization-server/which-grant/) you are implementing you will need to implement a number of repository interfaces. Each grant documentation page lists which repositories are required, and each repository interface has it's own documentation page. The repositories are expected to return (on success) instances of [entity interfaces](https://github.com/thephpleague/oauth2-server/tree/V5-WIP/src/Entities/Interfaces); to make integration with your existing entities and models as easy as possible though, all required methods have been implemented as traits that you can use. @@ -35,12 +35,26 @@ To generate the private key run this command on the terminal: openssl genrsa -out private.key 1024 {% endhighlight %} +If you want to provide a passphrase for your private key run this command instead: + +{% highlight shell %} +openssl genrsa -passout pass:_passphrase_ -out private.key 1024 +{% endhighlight %} + then extract the public key from the private key: {% highlight shell %} -openssl rsa -in private.key -pubout > public.key +openssl rsa -in private.key -pubout -out public.key {% endhighlight %} - + +or use your passphrase if provided on private key generation: + +{% highlight shell %} +openssl rsa -in private.key -passin pass:_passphrase_ -pubout -out public.key +{% endhighlight %} + The private key must be kept secret (i.e. out of the web-root of the authorization server). The authorization server also requires the public key. -The public key should be distributed to any services (for example resource servers) that validate access tokens. \ No newline at end of file +If a passphrase has been used to generate private key it must be provided to the authorization server. + +The public key should be distributed to any services (for example resource servers) that validate access tokens.