Update readme (#17)

Author: mbilski

README.md

@@ -5,58 +5,55 @@
 [![release](https://img.shields.io/github/release-pre/cloudentity/oauth2c.svg)](https://github.com/cloudentity/oauth2c/releases)
 [![downloads](https://img.shields.io/github/downloads/cloudentity/oauth2c/total)](https://github.com/cloudentity/oauth2c/releases)
 
-User-friendly command-line client for OAuth2
+`oauth2c` is a command-line tool for authenticating with OAuth2 providers. It supports all modern OAuth2 grant types and client authentication methods, allowing users to easily authenticate and access an OAuth2 provider's API.
 
 ![demo](https://user-images.githubusercontent.com/909896/176916616-36d803ef-832a-4bd8-ba8d-f6689e31ed22.gif)
 
+## Features
+
+* Supports all modern OAuth 2.0 grant types: authorization code, implicit, password, client credentials, refresh token, jwt bearer
+* Supports all client authentication methods: client secrets, private keys, client assertions, mtls
 
 ## Installation
 
+To install `oauth2c`, simply run the following command:
+
 ``` sh
 curl -sSfL https://raw.githubusercontent.com/cloudentity/oauth2c/master/install.sh | \
   sudo sh -s -- -b /usr/local/bin latest
 ```
 
-Binaries are also available on the [releases page].
+Alternatively, you can download a pre-built binary from the [releases page].
 
 [releases page]: https://github.com/cloudentity/oauth2c/releases
 
 ## Usage
 
+To use `oauth2c`, simply run the following command and follow the prompts:
+
 ``` sh
-$ oauth2c -h
-User-friendly command-line for OAuth2
-
-Usage:
-  oauthc [issuer url or json config file] [flags]
-
-Flags:
-      --assertion string         claims for jwt bearer assertion (standard claims such as iss, aud, iat, exp, jti are automatically generated)
-      --auth-method string       token endpoint authentication method
-      --client-id string         client identifier
-      --client-secret string     client secret
-      --grant-type string        grant type
-  -h, --help                     help for oauthc
-      --insecure                 allow insecure connections
-      --no-pkce                  disable proof key for code exchange (PKCE)
-      --password string          resource owner password credentials grant flow password
-      --pkce                     enable proof key for code exchange (PKCE)
-      --refresh-token string     refresh token
-      --response-mode string     response mode
-      --response-types strings   response type
-      --scopes strings           requested scopes
-      --signing-key string       path or url to signing key in jwks format
-      --tls-cert string          path to tls cert pem file
-      --tls-key string           path to tls key pem file
-      --tls-root-ca string       path to tls root ca pem file
-      --username string          resource owner password credentials grant flow username
+oauth2c [issuer url] [flags]
 ```
 
-> To make browser flows work add `http://localhost:9876/callback` redirect URL to your client.
+You will be asked to provide the necessary information, such as the grant type, client authentication method, and any other relevant details.
+
+Once authenticated, you will be able to use the access token to access the OAuth2 provider's API.
+
+> **Note**: To make browser flows work add `http://localhost:9876/callback` as a redirect URL to your client.
+
+For more information on the available options and arguments for each grant type, run `oauth2c --help`.
+
+## Examples
 
-## Grant types
+Here are a few examples of using oauth2c with different grant types and client authentication methods:
 
-### Authorization code
+### Grant types
+
+#### Authorization code
+
+This grant type involves a two-step process where the user first grants permission to access their data, and
+then the client exchanges the authorization code for an access token. This grant type is typically used
+in server-side applications.
 
 ``` sh
 oauth2c https://oauth2c.us.authz.cloudentity.io/oauth2c/demo \
@@ -70,7 +67,19 @@ oauth2c https://oauth2c.us.authz.cloudentity.io/oauth2c/demo \
   --no-pkce
 ```
 
-### Authorization code + PKCE
+#### Authorization code + PKCE
+
+The Proof Key for Code Exchange (PKCE) is an extension to the OAuth2 authorization code grant flow that
+provides additional security when authenticating with an OAuth2 provider. In the PKCE flow, the client
+generates a code verifier and a code challenge, which are then sent to the OAuth2 provider during
+the authorization request. The provider returns an authorization code, which the client then exchanges for
+an access token along with the code verifier. The provider verifies the code verifier to ensure that the
+request is coming from the same client that initiated the authorization request.
+
+This additional step helps to prevent attackers from intercepting the authorization code and using it to
+obtain an access token. PKCE is recommended for all public clients, such as single-page or mobile
+applications, where the client secret cannot be securely stored. oauth2c supports PKCE as an optional
+parameter when using the authorization code grant type.
 
 ``` sh
 oauth2c https://oauth2c.us.authz.cloudentity.io/oauth2c/demo \
@@ -84,7 +93,13 @@ oauth2c https://oauth2c.us.authz.cloudentity.io/oauth2c/demo \
   --pkce
 ```
 
-### Implicit
+#### Implicit
+
+This grant type is similar to the authorization code grant, but the access token is returned directly to
+the client without an intermediate authorization code. This grant type is typically used in single-page or
+mobile applications.
+
+> **Note**: The implicit flow is not recommended for use in modern OAuth2 applications. It does not provide a secure method for obtaining new access tokens. Instead, it is recommended to use the authorization code flow with PKCE (Proof Key for Code Exchange) for added security.
 
 ``` sh
 oauth2c https://oauth2c.us.authz.cloudentity.io/oauth2c/demo \
@@ -95,7 +110,13 @@ oauth2c https://oauth2c.us.authz.cloudentity.io/oauth2c/demo \
   --scopes openid,email,offline_access
 ```
 
-### Hybrid
+#### Hybrid
+
+To use the OAuth2 hybrid flow to obtain an authorization code and an ID token, the client first sends an authorization request to the OAuth2 provider. The request should include the client's ID, the desired response types.
+
+The OAuth2 provider will then return an authorization code and an ID token to the client, either in the response body or as fragment parameters in the redirect URL, depending on the response mode specified in the request. The client can then use the authorization code to obtain an access token by sending a token request to the OAuth2 provider.
+
+The ID token can be used to verify the identity of the authenticated user, as it contains information such as the user's name and email address. The ID token is typically signed by the OAuth2 provider, so the client can verify its authenticity using the provider's public key.
 
 ``` sh
 oauth2c https://oauth2c.us.authz.cloudentity.io/oauth2c/demo \
@@ -109,8 +130,11 @@ oauth2c https://oauth2c.us.authz.cloudentity.io/oauth2c/demo \
   --no-pkce
 ```
 
+#### Client credentials
 
-### Client credentials
+This grant type involves the client providing its own credentials (i.e. client ID and client secret) to
+the OAuth2 server, which then returns an access token. This grant type is typically used for
+server-to-server communication, where the client is a trusted server rather than a user.
 
 ``` sh
 oauth2c https://oauth2c.us.authz.cloudentity.io/oauth2c/demo \
@@ -122,9 +146,11 @@ oauth2c https://oauth2c.us.authz.cloudentity.io/oauth2c/demo \
 ```
 
 
-### Refresh token
+#### Refresh token
 
-> For this flow request refresh token using `offline_access` scope first.
+This grant type involves the client providing a refresh token to the OAuth2 server, which then returns
+a new access token. This grant type is used to obtain new access tokens when the original access
+token has expired.
 
 ``` sh
 oauth2c https://oauth2c.us.authz.cloudentity.io/oauth2c/demo \
@@ -135,7 +161,11 @@ oauth2c https://oauth2c.us.authz.cloudentity.io/oauth2c/demo \
   --refresh-token 1X1IvWR8p5rgKnH2YNmHGd4pZp8Dq-85xzUQuJejT_g.O_DS8Y4eiTS5jZ47_eBv3VbwP4zQUyxjNVW93AyU82k
 ```
 
-### Resource Owner Password Credentials Flow
+#### Password
+
+This grant type involves the client providing the user's username and password to the OAuth2 server, which
+then returns an access token. This grant type should only be used in secure environments, as it involves
+sending the user's credentials to the OAuth2 server.
 
 ``` sh
 oauth2c https://oauth2c.us.authz.cloudentity.io/oauth2c/demo \
@@ -146,7 +176,11 @@ oauth2c https://oauth2c.us.authz.cloudentity.io/oauth2c/demo \
   --scopes openid
 ```
 
-### JWT Bearer
+#### JWT Bearer
+
+This grant type involves the client providing a JSON Web Token (JWT) to the OAuth2 server, which then returns
+an access token. This grant type is typically used when the client is a trusted third-party, such as a JWT
+issuer.
 
 ``` sh
 oauth2c https://oauth2c.us.authz.cloudentity.io/oauth2c/demo \
@@ -159,9 +193,13 @@ oauth2c https://oauth2c.us.authz.cloudentity.io/oauth2c/demo \
   --assertion '{"sub":"[email protected]"}'
 ```
 
-## Auth methods
+### Auth methods
 
-### Client Secret Basic
+#### Client Secret Basic
+
+This client authentication method involves the client sending its client ID and client secret as part of the
+HTTP Basic authentication header in the request to the OAuth2 server. This method is simple and widely
+supported, but it is less secure than other methods because the client secret is sent in the clear.
 
 ``` sh
 oauth2c https://oauth2c.us.authz.cloudentity.io/oauth2c/demo \
@@ -172,7 +210,12 @@ oauth2c https://oauth2c.us.authz.cloudentity.io/oauth2c/demo \
   --scopes introspect_tokens,revoke_tokens
 ```
 
-### Client Secret Post
+#### Client Secret Post
+
+This client authentication method involves the client sending its client ID and client secret as part of
+the request body in the request to the OAuth2 server. This method provides more security than the
+basic authentication method, but it requires the request to be sent via HTTPS to prevent the client secret
+from being intercepted.
 
 ``` sh
 oauth2c https://oauth2c.us.authz.cloudentity.io/oauth2c/demo \
@@ -183,7 +226,11 @@ oauth2c https://oauth2c.us.authz.cloudentity.io/oauth2c/demo \
   --scopes introspect_tokens,revoke_tokens
 ```
 
-### Client Secret JWT
+#### Client Secret JWT
+
+This client authentication method involves the client signing a JSON Web Token (JWT) using its client secret,
+and then sending the JWT to the OAuth2 server. This method provides a higher level of security than the
+basic or post methods, as the client secret is never sent in the clear.
 
 ``` sh
 oauth2c https://oauth2c.us.authz.cloudentity.io/oauth2c/demo \
@@ -194,7 +241,11 @@ oauth2c https://oauth2c.us.authz.cloudentity.io/oauth2c/demo \
   --scopes introspect_tokens,revoke_tokens
 ```
 
-### Private Key JWT
+#### Private Key JWT
+
+This client authentication method involves the client signing a JSON Web Token (JWT) using its private key,
+and then sending the JWT to the OAuth2 server. This method provides a higher level of security than the
+JWT methods using a client secret, as the private key is never shared with the OAuth2 server.
 
 ``` sh
 oauth2c https://oauth2c.us.authz.cloudentity.io/oauth2c/demo \
@@ -205,7 +256,12 @@ oauth2c https://oauth2c.us.authz.cloudentity.io/oauth2c/demo \
   --scopes introspect_tokens,revoke_tokens
 ```
 
-### TLS Client Auth
+#### TLS Client Auth
+
+This client authentication method involves the client providing its own certificate as part of the TLS
+handshake when connecting to the OAuth2 server. This method provides a high level of security, as the
+client's identity is verified using a trusted certificate authority. However, it requires the OAuth2
+server to support TLS client authentication, which may not be supported by all OAuth2 providers.
 
 ``` sh
 oauth2c https://oauth2c.us.authz.cloudentity.io/oauth2c/demo \
@@ -216,3 +272,11 @@ oauth2c https://oauth2c.us.authz.cloudentity.io/oauth2c/demo \
   --auth-method tls_client_auth \
   --scopes introspect_tokens,revoke_tokens
 ```
+
+## License
+
+`oauth2c` is released under the [Apache v2.0](http://www.apache.org/licenses/LICENSE-2.0).
+
+## Contributing
+
+We welcome contributions! If you have an idea for a new feature or have found a bug, please open an issue on GitHub.