j1_template_mde 2018.4.11 → 2018.4.12

data/lib/starter_web/pages/start/documentation/user_guide/240_auth_manager/000_includes/attributes.asciidoc

@@ -1,119 +0,0 @@
-// ~/document_base_folder/000_includes
-//  Asciidoc attribute includes:                 attributes.asciidoc
-// -----------------------------------------------------------------------------
-
-
-// URLs - Internal references and/or sources on the Internet
-// -----------------------------------------------------------------------------
-tag::urls[]
-
-:jekyll-home-news:                                https://jekyllrb.com/news/
-
-:patreon-home:                                    https://patreon.com/
-
-:wikipedia-en-gdpr:                               https://en.wikipedia.org/wiki/General_Data_Protection_Regulation
-
-:j1-gh-jekyllone-template-dev:                    https://github.com/jekyll-one/j1_template_mde_dev
-:j1-gh-jekyllone-j1-images:                       https://github.com/jekyll-one/j1_images
-:j1-gh-jekyllone-j1-image-git-repo:               https://github.com/jekyll-one/j1_image.git
-:j1-jekyllone-images:                             https://hub.docker.com/u/jekyllone/
-:j1-jekyllone-images-j1image:                     https://hub.docker.com/r/jekyllone/j1image/
-:j1-jekyllone-images-j1app:                       https://hub.docker.com/r/jekyllone/j1app/
-:j1-jekyllone-images-j1base:                      https://hub.docker.com/r/jekyllone/j1base/
-:j1-jekyllone-images-j1:                          https://hub.docker.com/r/jekyllone/j1/
-
-:j1-kickstarter-docker-in-a-day:                  /pages/start/kickstarter/docker_in_a_day/getting_started/
-:j1-kickstarter-private-sites:                    /pages/start/kickstarter/j1_private_sites/100_introduction/
-
-
-:j1-images-in-a-day-intro:                        /pages/start/kickstarter/j1_images_in_a_day/intro/
-:j1-images-in-a-day-run-and-develop:              /pages/start/kickstarter/j1_images_in_a_day/run_and_develop/
-:j1-images-in-a-day-create-images:                /pages/start/kickstarter/j1_images_in_a_day/create_docker_images/
-:j1-images-in-a-day-cheatsheet:                   /pages/start/kickstarter/j1_images_in_a_day/j1_images_cheatsheet/
-:j1-images-in-a-day-j1-images-project:            /pages/start/kickstarter/j1_images_in_a_day/j1_images_project/
-
-:j1-private-sites-in-a-day-intro:                 /pages/start/kickstarter/j1_private_sites/100_introduction/
-
-:envygeeks-home:                                  https://envygeeks.io/
-:envygeeks-docker-template:                       https://github.com/envygeeks/docker-template
-:envygeeks-wiki:                                  https://github.com/envygeeks/docker-template/wiki
-
-:docker-docs:                                     https://docs.docker.com/
-:docker-docs-squash-image-layers:                 http://docs.docker.oeynet.com/engine/reference/commandline/build/#squash-an-images-layers-squash-experimental-only
-:docker-hub-jekyll-jekyll-image:                  https://hub.docker.com/r/jekyll/jekyll/
-
-:ruby-core-erb:                                   https://ruby-doc.org/stdlib-2.5.3/libdoc/erb/rdoc/ERB.html
-
-end::urls[]
-
-
-// Tags - Asciidoc attributes used internally
-// -----------------------------------------------------------------------------
-tag::tags[]
-
-:window:                                          window="_blank"
-:figure-caption:                                  Figure
-:images-dir:                                      pages/documentation/100_user_guide/200_modules/240_auth_manager
-:y:                                               icon:check[role="green"]
-:n:                                               icon:times[role="red"]
-:c:                                               icon:file-alt[role="blue"]
-:beginner:                                        icon:battery-quarter[role="md-blue"]
-:inter:                                           icon:battery-half[role="md-blue"]
-:advanced:                                        icon:battery-full[role="md-blue"]
-:emdash:                                          —
-:bullet:                                          •
-:bigbullet:                                       ●
-:bigbigbullet:                                    ⬤
-:dot:                                             .
-:dotdot:                                          ..
-:middot:                                          ·
-
-end::tags[] 
-
-
-// Data - Data elements for Asciidoctor extensions
-// -----------------------------------------------------------------------------
-tag::data[]
-
-:data-download-image-create-starter:              "pages/documentation/100_user_guide/200_modules/240_auth_manager/download_image_create_starter.800x600.png, Create a starter web skeleton"
-:data-run-container-build-start-web:              "pages/documentation/100_user_guide/200_modules/240_auth_manager/run_container_build_start_web.800x400.png, Build and run the starter web"
-:data-running-starter-web:                        "pages/documentation/100_user_guide/200_modules/240_auth_manager/run_starter_web.800x700.png, Run the starter web in a browser"
-
-:data-j1-runtime-system:                          "pages/documentation/100_user_guide/200_modules/240_auth_manager/j1_runtime_system-1280x600.png, J1 Runtime System for content development"
-:data-j1-development-system:                      "pages/documentation/100_user_guide/200_modules/240_auth_manager/j1_development_system-1280x600.png, J1 Development System for full-stack development"
-
-:data-2-tier-architecture:                        "pages/documentation/100_user_guide/200_modules/240_auth_manager/2-tier-architecture-1280x600.png, 2-Tier Architecture"
-:data-3-tier-architecture:                        "pages/documentation/100_user_guide/200_modules/240_auth_manager/3-tier-architecture-1280x600.png, 3-Tier Architecture"
-:data-web-app-ruby-rack:                          "pages/documentation/100_user_guide/200_modules/240_auth_manager/rack_based_web_app-1280x600.png, Rack-based J1 Web Application"
-
-:data-j1-authclient-icon:                         "pages/documentation/100_user_guide/200_modules/240_auth_manager/j1-app-authclient-icon.1280x600.png, J1 AuthClient Icon"
-:data-j1-authclient-signin:                       "pages/documentation/100_user_guide/200_modules/240_auth_manager/j1-app-authclient-signin.1280x700.png, J1 AuthClient SignIn Dialog"
-:data-j1-authclient-signout:                      "pages/documentation/100_user_guide/200_modules/240_auth_manager/j1-app-authclient-signout.1280x700.png, J1 AuthClient SignOut Dialog"
-:data-j1-disqus-comment-dialog:                   "pages/documentation/100_user_guide/200_modules/240_auth_manager/j1-disqus-comment-dialog.1280x500.png, J1 Disqus Comment Dialog"
-
-
-
-
-:gh-oauth-autorization-page-data:                 "pages/documentation/100_user_guide/200_modules/240_auth_manager/gh-oauth-autorization-page.png, GH OAuth autorization page used by Jekyll One"
-:gh-oauth-login-page-data:                        "pages/documentation/100_user_guide/200_modules/240_auth_manager/gh-oauth-login-page.png, GH login page for autorization used by Jekyll One"
-
-
-
-
-end::data[]
-
-
-// Product - Document (e.g release) information
-// -----------------------------------------------------------------------------
-tag::product_info[]
-:license:                                         MIT License
-:revdate:                                         2018
-:revnumber:                                       1.0.0
-end::product_info[]
-
-
-// Author - Author information
-// -----------------------------------------------------------------------------
-tag::authors[]
-:uri-author-juergen-adams                         https://jekyll.one
-end::authors[]

data/lib/starter_web/pages/start/documentation/user_guide/240_auth_manager/100_auth_manager.adoc

@@ -1,539 +0,0 @@
----
-title:                                  Authentication Module
-tagline:                                Template User Guide
-description:                            Authentication Module
-
-tags:                                   [ 
-                                          Authentication, Disqus, Google, 
-                                          Facebook, Twitter, Patreon, Template, 
-                                          Oauth, Oauth2, Module, Modules
-                                        ]
-resources:                              [ lightbox ]
-permalink:                              /user_guide/modules/auth_module/
-regenerate:                             false
-
-resource_options:
-
-  - toccer:
-      collapseDepth:                    3
----
-
-// Enable the Liquid Preprocessor
-// -----------------------------------------------------------------------------
-:page-liquid:
-
-// Set other global page attributes here
-// -----------------------------------------------------------------------------
-
-// Liquid procedures
-// -----------------------------------------------------------------------------
-{% capture set_env_entry_document %}themes/{{site.template.name}}/procedures/global/set_env_entry_document.proc{%endcapture%}
-
-// Initialize entry document paths
-// -----------------------------------------------------------------------------
-{% include {{set_env_entry_document}} init_folders=all %}
-
-// Load tags and urls
-// -----------------------------------------------------------------------------
-include::{includedir}/attributes.asciidoc[tag=tags]
-include::{includedir}/attributes.asciidoc[tag=urls]
-include::{includedir}/attributes.asciidoc[tag=data]
-
-// Additional Asciidoc page attributes goes here
-// -----------------------------------------------------------------------------
-
-// Include sub-documents
-// -----------------------------------------------------------------------------
-
-link:{jekyll-home}[Jekyll, {window}] and link:{gh-j1-starter-web-example}[J1 Template, {window}]
-are awesome, right? Static site, lightning fast, everything versioned in
-link:{git-home}[Git, {window}]. Simply managed by an good editor.
-
-What else could be ask for?
-
-link:{github-pages-home}[GitHub Pages, {window}] for example are very helpful
-to setup a project web site for free, to present a J1 Template based project 
-on the Internet for free. But what if you want to share that site with only a 
-selected number of people?
-
-To manage private Webs (or selected private content) for a static Jekyll site,
-you need authorization. As you know, a static site has no database. How to get
-users authenticated, how to give them access to private content without a 
-database, without a user management in behind?
-
-Seems not possible -- first place. A user management for authentication is 
-needed. No way.
-
-If you think next corner you may realize that your users, your audience for 
-the protected content are already known members at service providers like 
-_Disqus_, _Github_, _Facebook_, _Twitter_ etc. Nowadays, people have plenty 
-digital identities based on memberships at e.g. social networks or registered 
-already for communication services like _Disqus_.
-
-Why not using the user management of well known internet service providers
-widely used by billion of people?
-
-This could be ask for!
-
-== Introduction
-
-J1 Template has an authorisation system integrated. The authorisation 
-management implemented with J1 is based on *middleware* system written in Ruby. 
-The magic to secure a site created by Jekyll is done out of the box. No 
-additional software, no programming work is needed.
-
-How should that work?
-
-To bring in something in a position the the middle, the architecture
-of your static web has to be changed from a two layer (tier) into a three
-layer architecture. Uhh, sounds not easy to change the architecture of a
-simple static site!
-
-===  Web Applications
-
-It couldn't be called easy to add a authentication system to a static web; but 
-it is manageable using the web development capabilities of the programming 
-language *Ruby*. Ruby has a domain in creating applications for the Web. 
-Powerful Ruby Gems (libraries) like *Rack*, *Sinatra* and others like *Rails* 
-can be used for that. In short: the programming language *Ruby* is widely 
-used to create Web Applications.
-
-ifdef::backend-html5[]
-.2-Tier Architecture of a static web
-lightbox::2-tier-architecture[ 800, {data-2-tier-architecture} ]
-endif::[]
-
-But what are Web Applications?
-
-First of all, a *multi layered* and *dynamic* web page (or web site). A 
-simplified image of the architecture used for Jekyll webs transformed into 
-an web application is shown below.
-
-ifdef::backend-html5[]
-.Rack-based Jekyll Web Application
-lightbox::web-app-ruby-rack[ 800, {data-web-app-ruby-rack} ]
-endif::[]
-
-For a Jekyll web that is *transformed* into an web application, the web
-server can be seen as an interface to access the application; to the 
-processing chain at the core of an application. The transformer software, the 
-Ruby library *Rack* is sitting *in between* and adds additional functionality 
-for managing a requested page.
-
-To *activate* this new 3-layered web site, an application manager is used:
-*rackup*. The application manager *rackup* is controlled by an configuration
-file, the so-called rackup-file *config.ru*.
-
-Don't mind the details for now. What your web browser, the client, connects
-is not longer only the web server. Each request for the pages of a web goes
-over the a middleware *system*, managed by *Rack*.
-
-A middleware system based on Rack is not a *monolithic* block. It is a *stack*
-of *multiple* middleware components. What the name *Rack* implies. What is 
-called *Rack Middlewares* are the next great Ruby libraries (Gem) managing 
-a specific job, a *service* in such a chain.
-
-For now folks, keep in mind a *Jekyll Site* can be run as an App, transformed
-into an *web application* using *Rack*. Rack provides the *magic* in the middle
-to add additional dynamic processes -- the services -- e.g. for authentication.
-
-=== The Vision
-
-What's the vision: whenever someone tries to access a secured web site for
-protected, for private pages the user will be *authorized* using the
-*authorisation* system implemented by J1, for example against _Disqus_ or 
-_GitHub_ to make sure they're a member of your organization at Github. Or 
-simply known as a registered user at _Disqus_ for example.
-
-Service providers like _Disqus_, _Facebook_ or _Github_ and many others support 
-autorization request by third parties using SSO (Single Sign On) technologies. 
-That way: your web site is supported by those providers for authentication!
-
-=== Make it real
-
-The middlewares used by J1 based on *Rack* for autorisation is using the
-Ruby Gem *OmniAuth*. OmniAuth supports a huge number of *strategies* for
-authorisation. See a list of providers supported link:{omniauth-strategies}[from here, {window}].
-
-J1, for now, is focussing providers using *OAuth*, a authorization protocol
-widely used for *SSO* on the Internet by many important providers. Currently,
-the providers:
-
-* Disqus
-* Github
-* Facebook
-* Twitter
-* Patreon
-
-are supported for authentication using OAuth.
-
-
-== Overview
-
-As discussed in section <<Overview>>, the authorisation system of _J1 Template_
-is based on middlewares. From a outer perspective this system can be seen as a
-component providing *services* to a web site. In contrast to dynamic functions
-provided by CSS or Javascript functionality, services are controlling the
-whole web, not single pages.
-
-_J1 Template_ implements 2 authorisation methods:
-
-* explicit autorisation using the _J1 AuthClient_
-* implicit autorisation based on *Page Access*
-
-=== Explicit autorisation
-
-For all people using websites, explicit autorisation is well known: a login
-button, typically in the menu bar, allows to sign in or out. Quite the same
-for _J1_. 
-
-NOTE: The AuthClient is only activated, if a web site is detected as an *App*.
-If a site is started as a simple static web, *no* middlewares are available
-and no authentication services are provided.
-
-If a running web site is detected as an Web Application, the J1 AuthClient
-places an *SignIn* icon into the menu bar on the right. If a user is detected 
-as signed out, a *SignIn* icon is displayed.
-
-ifdef::backend-html5[]
-.J1 AuthClient Icon
-lightbox::j1-authclient-icon[ 800, {data-j1-authclient-icon} ]
-endif::[]
-
-On a click on the signin icon, a dialog starts (as an overlay) presenting the
-providers available to be authenticated with.
-
-ifdef::backend-html5[]
-.J1 AuthClient SignIn Dialog
-lightbox::j1-authclient-signin[ 800, {data-j1-authclient-signin} ]
-endif::[]
-
-No surprise, if a user is detected as authenticated for one of the providers
-available, the AuthClient changes the icon to *SignOut* and a dialog to stop
-the authorisation is displayed.
-
-ifdef::backend-html5[]
-.J1 AuthClient SignOut Dialog
-lightbox::j1-authclient-signout[ 800, {data-j1-authclient-signout} ]
-endif::[]
-
-All these sounds very common, seen hundred times each and every day on the
-internet. But it is *not* the same because you aren't logged in the web, you 
-are authenticated with a provider and logged in with the provider!
-
-What does that mean? J1 supports so-called *OAuth2 Authentication* for the
-supported service providers. And more than this. If a visitor signs in for a
-provider, a set of user specific data is retrived and stored locally with a
-web session cookie. This *user profile* is used to control the access for
-the pages of this private web. More details on that in section 
-<<Implicit autorisation>>.
-
-And more than this again. A successful authorisation results in an 
-provider-specific *Access Token*, valid for weeks to access the web without 
-any login dialog anymore.
-
-J1 support *multi-provider* authentication can use all active *Access Token*
-from all providers in parallell as long this token is valid. This is quite 
-usefull to use provider-based features of a _J1 Web_ using *multi-provider* 
-authentication capabilities. 
-
-If a user signs in for _Disqus_ first but changes the provider for _Github_, 
-e.g. to get access to pages limited to _Github_ users, the authorisation is 
-now valid for _Disqus_ *and* _GitHub_.
-
-ifdef::backend-html5[]
-.J1 Disqus Comment Dialog
-lightbox::j1-disqus-comment-dialog[ 800, {data-j1-disqus-comment-dialog} ]
-endif::[]
-
-=== Implicit autorisation
-
-J1 use a underlying access-control for all pages. Web pages belong to three
-categories:
-
-* public
-* private
-* premium
-
-*Public pages* are accessible for all vistors of a web, *no* authorisation is 
-need to get access to. For secured pages, *Private* and *Public* access can be 
-defined on a provider level. *Private pages* can be used to limit the access
-for a specific provider. Or to specific users authenticated with a provider.
-This may helpfull for a developer team at _Github_ to limit the access for
-a Project Web for all documents that are in state *Work-In-Progress* (WIP) or
-to internal documentation that shouldn't available for the public.
-
-It is very common that web sites offering *payed services* to the public as 
-well. If content is *not* for free, *Premium pages* are an option. Currently 
-the provider link:{patreon-home}[Patreon] is supported for premium services 
-to limit the access to vistors only, that have paid e.g a monthly fee.
-
-*Implicit autorisation* autorisation is based on *regular expressions* like
-so:
-
-[source, yaml]
-----
-content:
-  public:
-      - ^(\/assets)
-      - ^(\/pages\/about)
-      - ^(\/pages\/start)
-  private:
-    - ^(\/private)
-  premium:
-    - ^(\/premium)
-  user:
-    patreon:                          [ all ]
-  permission:
-    patreon:                          [ private, premium ]
-  condition:
-    patreon:
-      private:                        false
-      premium:
-        pledges:                      true
-----
-
-All pages, having a *perma-link* that starts with */premium* needs to be
-authenticated via the provider _Patreon_. But access is given only, if
-the monthly fee (pleges) were paid for the detected user (profile).
-
-Provider-based authentication is a simple and powerful method to implement
-restrictesd access to protected pages of a web. But it has limitations, no
-question. For many standard web sites, static or dynamic, a simple 
-authorisation scheme fits many, many use cases.
-
-On other hand, since the link:{wikipedia-en-gdpr}[General Data Protection Regulation]
-applies to *all* web sites collecting and/or procession personal data of their
-visitors in the European Union, a lot of *legal* constrains are to be taken 
-into account. *GDPR* is an regulation *framework*, not a clear law-wise 
-definition. 
-
-A lot is unclear in this area but one thing is for sure: the penalties 
-are high if a site does *not* apply this rules. If a vistor is using 
-*provider-based authentication*  to get access for the content of a web, it 
-is very certain that a global service provider is compliant with *GDPR*. As 
-all users has to agree the conditions, the term of use, implicisely such a web
-is *GDPR* compliant -- if additional information is given that personal data
-is *used*.
-
-== Auth Service configuration
-
-lorem:sentences[5]
-
-=== Service properties
-
-[source, yaml]
-----
-# ---------------------------------------------------------------
-# J1 Auth Manager (j1_auth)
-#
-# If a site is started as an app, this transforms the web into an
-# Web Application based on Rack and Sinatra using the Omniauth
-# software stack for authentication to enable User Management
-# and Authentication services for secured private web sites.
-j1_auth:
-  enabled:                              true
-  ssl:                                  false
-
-  content:
-    public:
-        - ^(\/assets)
-        - ^(\/pages\/about)
-        - ^(\/pages\/start)
-    private:
-      - ^(\/private)
-    premium:
-      - ^(\/premium)
-
-  provider:
-    activated:                          [ disqus, github, patreon ]
-    home_url:
-      disqus:                           https://disqus.com
-      facebook:                         https://facebook.com
-      github:                           https://github.com
-      patreon:                          https://patreon.com
-      twitter:                          https://twitter.com
-    scope:
-      disqus:                           [ read, write ]
-      facebook:                         [ email ]
-      github:                           [ user ]
-      patreon:                          [ users ]
-      twitter:                          [ user ]
-    user:
-      disqus:                           [ all ]
-      facebook:                         [ all ]
-      github:                           [ all ]
-      patreon:                          [ all ]
-      twitter:                          [ all ]
-    permission:
-      disqus:                           [ private ]
-      facebook:                         [ private ]
-      github:                           [ private ]
-      patreon:                          [ private, premium ]
-      twitter:                          [ private ]
-    condition:
-      disqus:                           false
-      facebook:                         false
-      github:                           false
-      twitter:                          false
-      patreon:
-        private:                        false
-        premium:
-          pledges:                      true
-----
-
-==== enabled
-
-Enables or disables the Auth Manager services for the web.
-If disabled, all pages are accessible without authentication.
-
-values:                             true|false
-default:                            false
-
-
-==== ssl
-
-Enforce SSL communication for the app. If you've got SSL
-set up, ensure SSL is enforced.
-
-values:                             true|false
-default:                            false
-
-
-==== content
-
-lorem:sentences[5]
-
-==== provider
-
-List of enabled OAuth providers to be used for the auth
-service for authentication. The first provider in a list
-is used for default.
-
-===== activated
-
-values:                             [disqus|github|facebook|patreon|twitter]
-default: 
-
-===== home_url
-
-lorem:sentences[5]
-
-===== scope
-
-lorem:sentences[5]
-
-===== user
-
-lorem:sentences[5]
-
-===== permission
-
-lorem:sentences[5]
-
-===== condition
-
-lorem:sentences[5]
-
-
-
-
-
-
-
-
-
-
-== Auth Client configuration
-
-lorem:sentences[5]
-
-=== Client properties
-
-[source, yaml]
-----
-# ------------------------------------------------------------------------------
-# 1. Default settings
-#
-defaults:
-  nav_authclient:
-    enabled:                            false
-    icon_family:                        Material Design Icons
-    icon_color:                         rgba_lighten
-    icon_color_hover:                   rgba_lighten_900
-    signin_icon:                        login
-    signout_icon:                       logout
-...
-# ------------------------------------------------------------------------------
-# 5. Auth client settings
-#
-nav_authclient:
-  enabled:                              true
-
-  auth_signin_modal:                        
-    title:                              SignIn
-    body_text: >
-                                        In order to get <b>signed in</b>, check one of the options below
-                                        and mark a provider for authentication.
-                                        You'll be <b>redirected</b> to authenticate with the provider
-                                        <b>selected</b>. If signed in <b>successfully</b>, you get back
-                                        to this site for the page requested.
-                                        </br></br>
-                                        <b>NOTE:</b> To access protected pages of this site,
-                                        authentication is needed only once.
-                                        </br></br>
- 
-                           
-  auth_signout_modal:                        
-    title:                              SignOut
-    body_text: >
-                                        In order to <b>signing out completely</b>, check the switch
-                                        below <b>to on</b>.
-                                        After signing out from this site, you'll be <b>redirected</b>
-                                        to the provider you're currently authenticated. From your
-                                        home page at the provider, you can sign out completely.    
-  auth_disqus:
-    id:                                 1
-    title:                              Disqus
-    text: >                             
-                                        SignIn to Disqus. Get access to all <b>PRIVATE</b> content pages.
-  auth_facebook:
-    id:                                 2
-    title:                              Facebook
-    text: >                             
-                                        SignIn to Facebook. Get access to all <b>PRIVATE</b> content pages.
-  auth_github:
-    id:                                 3
-    title:                              Github
-    text: >
-                                        SignIn to Github. Get access to all <b>PRIVATE</b> content pages.
-  auth_patreon:
-    id:                                 4
-    title:                              Patreon
-    text: >
-                                        SignIn to Patreon. Get access to all <b>PREMIUM</b> and <b>PRIVATE</b> content pages.
-  auth_twitter:
-    id:                                 5
-    home_url:                           "https://twitter.com"
-    title:                              Twitter
-    text: >                             
-                                        SignIn to Twitter. Get access to all <b>PRIVATE</b> content pages.
-----
-
-lorem:sentences[3]
-
-== Web App configuration
-
-lorem:sentences[5]
-
-
-
-== Configuration Cheat Sheet
-
-lorem:sentences[5]
-
-
-
-
-
-