documentation for PR #502

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';
+$privateKey = 'file://path/to/private.key';
-$publicKeyPath = 'file://path/to/public.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,
+    $privateKey,
-    $publicKeyPath
+    $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 %}
+{% endhighlight %}

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';
+$privateKey = 'file://path/to/private.key';
-$publicKeyPath = 'file://path/to/public.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,
+    $privateKey,
-    $publicKeyPath
+    $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());

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';
+$privateKey = 'file://path/to/private.key';
-$publicKeyPath = 'file://path/to/public.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,
+    $privateKey,
-    $publicKeyPath
+    $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 %}
+{% endhighlight %}

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';
+$privateKey = 'file://path/to/private.key';
-$publicKeyPath = 'file://path/to/public.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,
+    $privateKey,
-    $publicKeyPath
+    $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());

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';
+$privateKey = 'file://path/to/private.key';
-$publicKeyPath = 'file://path/to/public.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,
+    $privateKey,
-    $publicKeyPath
+    $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());

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.
+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.