docs: example of using a state token (#58)

* docs: example of using a state token

Closes #11

* provide extended example

* fix uri

* remove elixirls

Author: davydog187

README.md

@@ -32,7 +32,7 @@ google_config = %{
   scope: "openid email profile"
 }
 
-authorization_uri(google_config)
+OpenIDConnect.authorization_uri(google_config)
 ```
 
 Most major OAuth2 providers have added support for OpenIDConnect. [See a short list of most major adopters of OpenIDConnect](https://en.wikipedia.org/wiki/List_of_OAuth_providers).
@@ -93,22 +93,31 @@ Setting your app's session state is outside the scope of this library.
 ```elixir
 # router.ex
 get("/session", SessionController, :create)
-get("/session/authorization-uri", SessionController, :authorization_uri)
+get("/session/:provider/authorization-uri", SessionController, :authorization_uri)
 
 # session_controller.ex
-# you could also take the `provider` as a query param to pass into the function
-def authorization_uri(conn, _params) do
+def authorization_uri(conn, %{"provider" => "google"}) do
   google_config = Application.fetch_env!(:my_app, :google_oidc_config)
-  {:ok, uri} = OpenIDConnect.authorization_uri(google_config)
+
+  state_token = Base.encode64(:crypto.strong_rand_bytes(32), padding: false)
+  redirect_uri = url(Endpoint, ~p"/session/google/authorization-uri")
+  {:ok, uri} = OpenIDConnect.authorization_uri(google_config, redirect_uri, %{state: state})
 
-  json(conn, %{uri: uri})
+  conn
+  # Store the state token for verifying we get the same one back
+  |> put_session(:state_token, state_token)
+  |> redirect(external: uri)
 end
 
 # The `Authentication` module here is an imaginary interface for setting session state
 def create(conn, params) do
   google_config = Application.fetch_env!(:my_app, :google_oidc_config)
 
-  with {:ok, tokens} <- OpenIDConnect.fetch_tokens(google_config, params["code"]),
+  # State token should be passed back by the provider
+  state_token = params["state"]
+
+  with true <- valid_state_token?(conn, state_token),
+       {:ok, tokens} <- OpenIDConnect.fetch_tokens(google_config, params["code"]),
        {:ok, claims} <- OpenIDConnect.verify(google_config, tokens["id_token"]),
        {:ok, user} <- Authentication.call(google_config, Repo, claims) do
 
@@ -119,6 +128,14 @@ def create(conn, params) do
     _ -> send_resp(conn, 401, "")
   end
 end
+
+defp valid_state_token?(conn, token) do
+  # Pull out the state token from session
+  case get_session(conn, :state_token) do
+    nil -> false
+    state_token -> Plug.Crypto.secure_compare(state_token, token)
+  end
+end
 ```
 
 ## Authors

lib/openid_connect.ex

@@ -68,10 +68,32 @@ defmodule OpenIDConnect do
   The `params` option can be used to add additional query params to the URI
 
   Example:
+
       OpenIDConnect.authorization_uri(:google, %{"hd" => "dockyard.com"})
 
+  > ### Warning {: .warning}
   > It is *highly suggested* that you add the `state` param for security reasons. Your
-  > OpenID Connect provider should have more information on this topic.
+  > OpenID Connect provider should have more information on this topic. 
+  > See [Google's Documentation](https://developers.google.com/identity/openid-connect/openid-connect#createxsrftoken) as an exampl
+
+  ### Creating a state token
+
+  A state token should be a hashed cookie or a randomly generated value of reasonable length
+
+      state_token = Base.encode64(:crypto.strong_rand_bytes(32), padding: false)
+
+      OpenIDConnect.authorization_uri(:google, %{"hd" => "dockyard.com", "state" => state_token})
+
+      # Store token somewhere, such as your session state
+      conn = Plug.Conn.put_session(conn, :state_token, state_token)
+
+  ### Validating a state token
+
+  Once your application's callback has been fired, validate the token received vs the one
+  you have stored.
+
+      Plug.Crypto.secure_compare(Plug.Conn.get_session(conn, :state_token), params["state"])
+
   """
   @spec authorization_uri(
           config(),