clarify auth docs

k0ka · Jan 30, 2024 · Jan 17, 2024 · Jan 17, 2024 · Jan 17, 2024 · Jan 17, 2024
commit a3d279211375383dfc6c95bf189afb5f98fb5a56
diff --git a/doc/services/identity/v3/create.rst b/doc/services/identity/v3/create.rst
@@ -6,7 +6,9 @@ In order to work with the service you have to :doc:`setup the client </setup>` f
 Service can be created via ``identityV3()`` method of the ``OpenStack`` object.
 
 .. sample:: Identity/v3/create.php
+    :full:
 
 A list of additional options can be passed to the method. For example, to change the region:
 
 .. sample:: Identity/v3/create_with_region.php
+    :full:
diff --git a/doc/setup.rst b/doc/setup.rst
@@ -17,32 +17,27 @@ There are different ways to provide the authentication credentials. See the :doc
 section for the full list of options. You should provide credentials to the ``OpenStack`` constructor as an array
 the same way you provide options to ``generateToken`` method of the ``Identity`` service.
 
-Authenticate with user ID
-~~~~~~~~~~~~~~~~~~~~~~~~~
-
-.. sample:: Setup/user_id.php
-
 Authenticate with username
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+--------------------------
 
-.. sample:: Setup/username.php
+The most common way to authenticate is using the username and password of the user. You should also provide the Domain ID
+as usernames will not be unique across an entire OpenStack installation
 
-Authenticate application credential ID
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. sample:: Setup/username.php
 
-.. sample:: Setup/application_credential_id.php
+Authenticate with user ID
+--------------------------
 
-Authenticate from ID
-~~~~~~~~~~~~~~~~~~~~
+.. sample:: Setup/user_id.php
 
-.. sample:: Setup/from_id.php
+Authenticate application credential ID
+--------------------------------------
 
-Scope to project ID
-~~~~~~~~~~~~~~~~~~~
+.. sample:: Setup/application_credential_id.php
 
-.. sample:: Setup/scoped_to_project_id.php
+Authenticate using token ID
+--------------------------
 
-Scope to project name
-~~~~~~~~~~~~~~~~~~~~~
+If you already have a valid token, you can use it to authenticate.
 
-.. sample:: Setup/scoped_to_project_name.php
+.. sample:: Setup/token_id.php
diff --git a/samples/Identity/v3/create_with_region.php b/samples/Identity/v3/create_with_region.php
@@ -4,7 +4,6 @@
 
 $openstack = new OpenStack\OpenStack([
     'authUrl' => '{authUrl}',
-    'region'  => '{region}',
     'user'    => [
         'id'       => '{userId}',
         'password' => '{password}'

diff --git a/samples/Setup/scoped_to_project_id.php b/samples/Setup/scoped_to_project_id.php
diff --git a/samples/Setup/scoped_to_project_name.php b/samples/Setup/scoped_to_project_name.php
diff --git a/samples/Setup/from_id.php → samples/Setup/token_id.php b/samples/Setup/from_id.php → samples/Setup/token_id.php