From 2df69a40af8b431cc45b6173b74360dcd805928d Mon Sep 17 00:00:00 2001
From: andres <afquinteromoreano@gmail.com>
Date: Tue, 2 Jan 2024 12:45:43 -0500
Subject: [PATCH] Improves README

---
 DESCRIPTION                          |   2 +-
 README.md                            |  88 ++++++++++++++++++---------
 {figures => man/figures}/tapLock.png | Bin
 {figures => man/figures}/tapLock.svg |   0
 4 files changed, 60 insertions(+), 30 deletions(-)
 rename {figures => man/figures}/tapLock.png (100%)
 rename {figures => man/figures}/tapLock.svg (100%)

diff --git a/DESCRIPTION b/DESCRIPTION
index 5457cb7..f5427b1 100644
--- a/DESCRIPTION
+++ b/DESCRIPTION
@@ -1,6 +1,6 @@
 Package: tapLock
 Title: Seamless SSO for R applications
-Version: 0.1.0.9000
+Version: 0.1.0
 Authors@R: 
     c(person(given = "ixpantia, SRL",
              role = "cph",
diff --git a/README.md b/README.md
index 51adafe..d4e8064 100644
--- a/README.md
+++ b/README.md
@@ -1,55 +1,84 @@
-# tapLock
+# tapLock <img src="man/figures/tapLock.png" align="right" width=120 height=139 alt="" />
 
-## Example Shiny App with Entra ID Authentication
+Secure your R applications with OpenID Connect and OAuth 2.0.
 
-```R
-library(shiny)
-library(tapLock)
+## Summary
+
+tapLock is an R library that provides a simple interface to
+integrate OpenID Connect / OAuth 2.0 authentication into you Shiny
+applications and Plumber APIs. tapLock uses a unique approach to
+effectively secure your applications without the need to write almost
+any code.
+
+## Authentication providers
+
+tapLock supports the following authentication providers:
+
+- [Google](https://developers.google.com/identity/protocols/oauth2/openid-connect)
+- [Microsoft Entra ID](https://www.microsoft.com/en-us/security/business/identity-access/microsoft-entra-id)
+
+> If you need support for other providers, please contact us at
+> [hola@ixpantia.com](mailto:hola@ixpantia.com). Or, if you are a
+> developer, you can contribute to the project by adding support for
+> additional providers.
+
+## Security Model
+
+tapLock is unique in its approach to securing Shiny applications and
+Plumber APIs. tapLock utilizes middlewares that intercept all incoming
+requests (both HTTP and WebSocket requests) and validates the
+authentication token. This approach allows tapLock to be lean and
+efficient since no expensive WebSocket connections are started until
+the user is authenticated. It also prevents sensitive data in the UI
+portion of the application from being exposed to unauthenticated users.
+
+## How to use tapLock with Shiny
+
+#### 1. Install tapLock
+
+``` r
+pak::pak("ixpantia/taplock")
+```
+
+#### 2. Create an authentication configuration
+
+``` r
+library(taplock)
 
 auth_config <- new_openid_config(
   provider = "entra_id",
+  # The following values are obtained from the authentication provider
   tenant_id = Sys.getenv("TENANT_ID"),
   client_id = Sys.getenv("CLIENT_ID"),
   client_secret = Sys.getenv("CLIENT_SECRET"),
+  # This should be the URL of your application
   app_url = Sys.getenv("APP_URL")
 )
+```
 
-ui <- fluidPage(
-  tags$h1("tapLock example"),
-  textOutput("user")
-)
-
-server <- function(input, output, session) {
+#### 3. Secure your Shiny application
 
-  output$user <- renderText({
-    given_name <- get_token_field(token(), "given_name")
-    family_name <- get_token_field(token(), "family_name")
-    expires_at <- expires_at(token())
-    glue::glue(
-      "Hello {given_name} {family_name}!",
-      "Your authenticated session will expire at {expires_at}.",
-      .sep = " "
-    )
-  })
-
-}
-```
+To secure your Shiny Application you will simply need to expose
+an `sso_shiny_app` instead of a regular `shinyApp` at the end of your
+`app.R` file.
 
-## Example Shiny App with Google Authentication
+Here is an example of a Shiny application that uses tapLock to secure
+itself:
 
-```R
+``` r
 library(shiny)
 library(tapLock)
 
 auth_config <- new_openid_config(
-  provider = "google",
+  provider = "entra_id",
+  tenant_id = Sys.getenv("TENANT_ID"),
   client_id = Sys.getenv("CLIENT_ID"),
   client_secret = Sys.getenv("CLIENT_SECRET"),
   app_url = Sys.getenv("APP_URL")
 )
 
 ui <- fluidPage(
-  tags$h1("tapLock example"),
+  tags$h1("r.sso example"),
   textOutput("user")
 )
 
@@ -67,5 +96,6 @@ server <- function(input, output, session) {
   })
 
 }
-```
 
+sso_shiny_app(auth_config, ui, server)
+```
diff --git a/figures/tapLock.png b/man/figures/tapLock.png
similarity index 100%
rename from figures/tapLock.png
rename to man/figures/tapLock.png
diff --git a/figures/tapLock.svg b/man/figures/tapLock.svg
similarity index 100%
rename from figures/tapLock.svg
rename to man/figures/tapLock.svg