Merge branch '218-document-new-oauth-grants' into 'master'

Resolve "Document new OAuth grants"

Closes #218

See merge request genesys-pgr/genesys-server!122

src/main/asciidoc/api/security.adoc

@@ -45,6 +45,9 @@ Most OAuth libraries, including https://gitlab.croptrust.org/genesys-pgr/genesys
 Java library, will automatically obtain the access token following the OAuth protocol. This
 section describes how to manually obtain the tokens.
 
+
+==== Authorization Grant
+
 Log-in to Genesys with your account or Google+
 
 Obtain a verifier code by granting access to the "Genesys API reference" client. This is
@@ -63,6 +66,42 @@ Copy the authorization code: *THECODE* (looks like: 7wXP1r) and from shell, exec
 $ curl 'https://sandbox.genesys-pgr.org/oauth/token?grant_type=authorization_code&client_id=CLIENTID&client_secret=SECRET&redirect_uri=oob&code=THECODE'
 ----
 
+==== Username & Password
+
+The **password grant** is available to trusted, secure clients (e.g. desktop
+applications) where the user's password will not be captured or stored -- i.e.
+it will be used once.
+
+----
+$ curl 'https://sandbox.genesys-pgr.org/oauth/token' --data 'scope=write+read&grant_type=password&username=USERNAME&password=PASSWORD&client_id=CLIENT_ID&client_secret=CLIENT_SECRET'
+----
+
+==== Client Credentials
+
+System-to-System integration should not require user interaction. For that
+specific purpose, Genesys allows for OAuth 2.0 "Client Credentials" grant.
+
+With Genesys release 2.3 the *Client authentication grant* is also supported.
+Kindly contact the helpdesk@genesys-pgr.org for information how to enable
+system-to-system integration and to grant your Client the appropriate
+permissions on Genesys.
+
+**Note**: The client will be able to modify any data on Genesys on your behalf.
+
+Read the section <<oauth, Client Credential Grant>>.
+
+To obtain a valid (but short-lived) access token, a simple **POST** request to
+Genesys is required:
+
+----
+$ curl -X POST 'https://sandbox.genesys-pgr.org/oauth/token?grant_type=client_credentials&client_id=CLIENTID&client_secret=SECRET&redirect_uri=oob'
+----
+
+This type of grant takes out the **user** authentication and authenticates the
+remote system with Genesys, immediately issuing an access token.
+
+==== Successful authorization
+
 The server will respond with access token details in JSON format:
 
 [source,json]
@@ -97,16 +136,6 @@ or include it in the request URL as a query string parameter:
 $ curl 'https://sandbox.genesys-pgr.org/api/v0/me?access_token=OAUTH-ACCESS-TOKEN'
 ----
 
-=== System-to-System integration
-
-With Genesys release 2.3 the *Client authentication grant* is also supported. Kindly
-contact the helpdesk@genesys-pgr.org for information how to enable system-to-system
-integration and to grant your Client the appropriate permissions on Genesys.
-
-**Note**: The client will be able to modify any data on Genesys on your behalf.
-
-Read the section <<oauth, Client Credential Grant>>.
-
 === Using the refresh token
 
 OAuth access tokens have a fairly short lifetime. When an access token expires, the