From 5e502f22cf589230262b517b60234bc51d703421 Mon Sep 17 00:00:00 2001
From: "Hahn Axel (hahn)" <axel.hahn@unibe.ch>
Date: Tue, 17 Sep 2024 13:45:13 +0200
Subject: [PATCH] add markdown in docs folder
---
Readme.md | 95 +------------
docs/10_Description.md | 9 ++
docs/20_Features.md | 6 +
docs/30_Requirements.md | 4 +
docs/40_Installation.md | 5 +
docs/50_Configuration.md | 62 +++++++++
docs/90_Development.md | 7 +
docs/_index.md | 11 ++
docs/config.json | 26 ++++
docs/style.css | 290 +++++++++++++++++++++++++++++++++++++++
10 files changed, 421 insertions(+), 94 deletions(-)
create mode 100644 docs/10_Description.md
create mode 100644 docs/20_Features.md
create mode 100644 docs/30_Requirements.md
create mode 100644 docs/40_Installation.md
create mode 100644 docs/50_Configuration.md
create mode 100644 docs/90_Development.md
create mode 100644 docs/_index.md
create mode 100644 docs/config.json
create mode 100644 docs/style.css
diff --git a/Readme.md b/Readme.md
index 1621bf7..db4370a 100644
--- a/Readme.md
+++ b/Readme.md
@@ -5,102 +5,9 @@ A login page for multiple AAI organisations.
* PHP
* License: GNU GPL 3.0
* Source: https://git-repo.iml.unibe.ch/iml-open-source/login-aai
+* Docs: see docs folder
⚠️ Work in progress!
-## Description
-
-We have projects with multiple organisations in different countries.
-We used the WAYF script in the login page so far.
-
-When editing login pages in Ilias 9 then javascript is now filtered out while saving. That's why we couldn't embed our current WAYF script anymore.
-This is a standalone login page that offers a list of organisations and can be customized.
-
-This reads the discofeed. By a given positive list of Idps it shows a list of identity providers to login on the visitors organisation.
-
-## Features
-
-* Displays a list of allowed Identity providers
-* The list is filtered during typing in the search field. When entering multiple words all keywords must match.
-* The filter is stored in localstorage of the webbrowser. On reload or the next week the last filter will be activated.
-* A set of filter buttons by TLD will be generated. It is shown when minimum 2 TLDs were found.
-
-## Requirements
-
-* PHP 8.2
-* PHP web aaplication with mod_shibboleth
-
-## Installation
-
-* In the webroot create a subfolder "login_aai".
-* Set a Link for Login to `/login_aai/` where needed
-* Copy config.php.dist to config.php and make your changes.
-
-## Configuration
-
-First an example configuration:
-
-```php
-<?php
-return [
-
- 'title' => 'AAI Login',
-
- // -- language to fetch texts in discofeed
- 'lang' => 'de',
-
- // -- enable one of it:
- 'mode' => 'boxes',
- // 'mode' => 'wayf',
-
- // -- maintenance hint or other message on top
- // 'text-info' => '+++ Hinweis +++ Hinweis +++ Hinweis +++ Hinweis +++',
-
- // -- text before and after
- 'text-before' => '<p>Studierende und Dozenten nutzen in der Regel das nachfolgende "Anmelden":</p>',
- 'text-after' => '<br><br><h2>Anmeldung ohne AAI</h2>
- <p>
- Klicken Sie auf: <br />
- <a href="/login.php" onclick="">Gast-Zugang</a>
- </p>',
-
- // -- positive list of IDPs
- 'idps' => [
- "https://aai-idp.unibe.ch/idp/shibboleth",
- "https://aai.insel.ch/idp/shibboleth",
- "https://aai-logon.vho-switchaai.ch/idp/shibboleth",
- "https://aai-logon.unibas.ch/idp/shibboleth",
- ],
-
- // -- return URL
- 'return-url' => '/shib_login.php'
-
- // -- cache for discofeed
- 'cachefile' => 'discofeed.json',
- 'cachettl' => 60*60,
-
-];
-```
-
-| Key | Type | Description
-|-- |-- |--
-| title | string | Title of the login page; used for title tag and h1 header
-| lang | string | Language to detect texts in discofeed as 2 letter code; If the language is not found it takes the 1st text item
-| mode | string | Selection mode; one of <br>-`"wayf"` Selection with WAYF script from Switch or<br>- `"boxes"` Boxes with images incl. filter field
-| text-info | string | When not empty: show a warning banner with its text on top eg. for maintenance messages
-| text-before-wayf | string | Text to show before wayf select box (for mode = "wayf" only)
-| text-after-logins | string | Fisnishing text after
-| idps | array | List of enabled idps to whitelist; it will filtered by enabled organisatzions by shibboleth
-| return-url | string | Return url to your application afer logging in on then organization url<br>- '/shib_login.php' is for Ilias LMS
-| cachefile | string | Releative path for cache file; default: discofeed.json
-| cachettl | integer | Caching time for cache file (discofeed.json ); default: 60 min
-
-## Devlopment hints
-
-* Requirements: local installation of php; you can use its internal webservice
-* Extract files in a local folder or use git clone
-* start `php -S localhost:9000` and open <http://localhost:9000> in your webbrowser
-* Get the files of the discofeed from a production machine running shibboleth and store it as discofeed cache file:<br> `curl https://example.com/Shibboleth.sso/DiscoFeed > discofeed.json`
-* After reachin cache TTL you can repeat the curl command or `touch discofeed.json`
diff --git a/docs/10_Description.md b/docs/10_Description.md
new file mode 100644
index 0000000..8542b98
--- /dev/null
+++ b/docs/10_Description.md
@@ -0,0 +1,9 @@
+## Description
+
+We have projects with multiple organisations in different countries.
+We used the WAYF script in the login page so far.
+
+When editing login pages in Ilias 9 then javascript is now filtered out while saving. That's why we couldn't embed our current WAYF script anymore.
+This is a standalone login page that offers a list of organisations and can be customized.
+
+This reads the discofeed. By a given positive list of Idps it shows a list of identity providers to login on the visitors organisation.
diff --git a/docs/20_Features.md b/docs/20_Features.md
new file mode 100644
index 0000000..0babcd2
--- /dev/null
+++ b/docs/20_Features.md
@@ -0,0 +1,6 @@
+## Features
+
+* Displays a list of allowed Identity providers
+* The list is filtered during typing in the search field. When entering multiple words all keywords must match.
+* The filter is stored in localstorage of the webbrowser. On reload or the next week the last filter will be activated.
+* A set of filter buttons by TLD will be generated. It is shown when minimum 2 TLDs were found.
diff --git a/docs/30_Requirements.md b/docs/30_Requirements.md
new file mode 100644
index 0000000..03d6241
--- /dev/null
+++ b/docs/30_Requirements.md
@@ -0,0 +1,4 @@
+## Requirements
+
+* PHP 8 (up to 8.3)
+* PHP web application with mod_shibboleth
diff --git a/docs/40_Installation.md b/docs/40_Installation.md
new file mode 100644
index 0000000..b8a7bd9
--- /dev/null
+++ b/docs/40_Installation.md
@@ -0,0 +1,5 @@
+## Installation
+
+* In the webroot create a subfolder "login_aai".
+* Set a Link for Login to `/login_aai/` where needed
+* Copy config.php.dist to config.php and make your changes.
diff --git a/docs/50_Configuration.md b/docs/50_Configuration.md
new file mode 100644
index 0000000..7f91ccf
--- /dev/null
+++ b/docs/50_Configuration.md
@@ -0,0 +1,62 @@
+## Configuration
+
+First an example configuration:
+
+```php
+<?php
+return [
+
+ 'title' => 'AAI Login',
+
+ // --- language for ui
+ 'lang' => 'de',
+
+ // -- enable one of it:
+ 'mode' => 'boxes',
+ // 'mode' => 'wayf',
+
+ // -- maintenance hint or other message on top
+ // 'text-info' => '+++ Hinweis +++ Hinweis +++ Hinweis +++ Hinweis +++',
+
+ // -- text before and after
+ 'text-before' => '<h2>AAI Login</h2>
+ <p>
+ Studierende und Dozenten nutzen in der Regel das Anmelden über ihre Organisation:
+ </p>',
+
+ 'text-after' => '<br><br><h2>Anmeldung ohne AAI</h2>
+ <p>
+ Klicken Sie auf: <br />
+ <a href="/login.php" onclick="">Gast-Zugang</a>
+ </p>',
+
+ // -- positive list of IDPs
+ 'idps' => [
+ "https://aai-idp.unibe.ch/idp/shibboleth",
+ "https://aai.insel.ch/idp/shibboleth",
+ "https://aai-logon.vho-switchaai.ch/idp/shibboleth",
+ "https://aai-logon.unibas.ch/idp/shibboleth",
+ ],
+
+ // -- return URL
+ 'return-url' => '/shib_login.php'
+
+ // -- cache for discofeed
+ 'cachefile' => 'discofeed.json',
+ 'cachettl' => 60*60,
+
+];
+```
+
+| Key | Type | Description
+|-- |-- |--
+| title | string | Title of the login page; used for title tag and h1 header
+| lang | string | Language to detect texts in discofeed as 2 letter code; If the language is not found it takes the 1st text item
+| mode | string | Selection mode; one of <br>-`"wayf"` Selection with WAYF script from Switch or<br>- `"boxes"` Boxes with images incl. filter field
+| text-info | string | When not empty: show a warning banner with its text on top eg. for maintenance messages
+| text-before-wayf | string | Text to show before wayf select box (for mode = "wayf" only)
+| text-after-logins | string | Fisnishing text after
+| idps | array | List of enabled idps to whitelist; it will filtered by enabled organisatzions by shibboleth
+| return-url | string | Return url to your application afer logging in on then organization url<br>- '/shib_login.php' is for Ilias LMS
+| cachefile | string | Releative path for cache file; default: discofeed.json
+| cachettl | integer | Caching time for cache file (discofeed.json ); default: 60 min
diff --git a/docs/90_Development.md b/docs/90_Development.md
new file mode 100644
index 0000000..a82bb5e
--- /dev/null
+++ b/docs/90_Development.md
@@ -0,0 +1,7 @@
+## Devlopment hints
+
+* Requirements: local installation of php; you can use its internal webservice
+* Extract files in a local folder or use git clone
+* start `php -S localhost:9000` and open <http://localhost:9000> in your webbrowser
+* Get the files of the discofeed from a production machine running shibboleth and store it as discofeed cache file:<br> `curl https://example.com/Shibboleth.sso/DiscoFeed > discofeed.json`
+* After reachin cache TTL you can repeat the curl command or `touch discofeed.json`
diff --git a/docs/_index.md b/docs/_index.md
new file mode 100644
index 0000000..5647791
--- /dev/null
+++ b/docs/_index.md
@@ -0,0 +1,11 @@
+# AAI Login page
+
+A login page for multiple AAI organisations.
+
+* PHP
+* License: GNU GPL 3.0
+* Source: https://git-repo.iml.unibe.ch/iml-open-source/login-aai
+
+⚠️ Work in progress!
+
+
\ No newline at end of file
diff --git a/docs/config.json b/docs/config.json
new file mode 100644
index 0000000..8b0fd01
--- /dev/null
+++ b/docs/config.json
@@ -0,0 +1,26 @@
+{
+ "title": "AAI Logon with Shibboleth",
+ "author": "Axel Hahn",
+ "tagline": "AAI login with Shibboleth handling multiple organizations",
+ "ignore": {
+ "files": ["30_PHP-client/Plugins/Checks/_skeleton.md"],
+ "folders": ["99_Not_Ready"]
+ },
+ "html": {
+ "auto_toc": true,
+ "auto_landing": false,
+ "date_modified": false,
+ "jump_buttons": true,
+ "edit_on_github_": "iml-it/__PROJECT__/tree/master/docs",
+ "edit_on": {
+ "name": "Gitlab",
+ "basepath": "https://git-repo.iml.unibe.ch/iml-open-source/login-aai/-/tree/main/docs"
+ },
+ "links": {
+ "Git Repo": "__GITURL__",
+ "IML Opensource": "https://os-docs.iml.unibe.ch/"
+ },
+ "theme": "daux-blue",
+ "search": true
+ }
+}
diff --git a/docs/style.css b/docs/style.css
new file mode 100644
index 0000000..45383c3
--- /dev/null
+++ b/docs/style.css
@@ -0,0 +1,290 @@
+/*
+ override css elements of daux.io blue theme
+ version 2023-11-10
+*/
+:root {
+ /* Axels Overrides */
+ --color-text: #234;
+ --link-color: #228;
+ --brand-color: var(--color-text);
+ --brand-background: var(--body-background);
+ --code-tag-border-color: #d8d8d8;
+ --hr-color: none;
+ --search-field-background: none;
+ --search-field-border-color: none;
+ --sidebar-background: var(--body-background);
+ --sidebar-border-color: none;
+ --sidebar-link-active-background: #e8f4f6;
+ --sidebar-link-active-background: #eee;
+ /* Axels custom values */
+ --axel_bg-toc: var(--body-background);
+ --axel_bg-toc-head: #f8f8f8;
+ --axel_brand-background: none;
+ --axel_brand-pre-background: rgb(255, 0, 51);
+ ;
+ --axel_brand-pre-background-hover: rgb(255, 0, 51);
+ ;
+ --axel_h1_header: none;
+ --axel_h1: #111;
+ --axel_h1-bg: none;
+ --axel_h1-bottom: 3px solid none;
+ --axel_h2: #222;
+ --axel_h2-bg: none;
+ --axel_h2-bottom: 0px solid #467;
+ --axel_h2-hero-bottom: 2px solid #912;
+ --axel_h3: #333;
+ --axel_h3-bottom: 0px solid #ddd;
+ --axel_h4: #444;
+ --axel_hero_bg: #f8f8f8;
+ --axel_img-border: 2px dashed #ccc;
+ --axel_nav-bg: #fcfcfc;
+ --axel_nav-buttomborder: #ddd;
+ --axel_pre-background: #f8f8f8;
+ --axel-th-background: #e0e4e8;
+ --axel-article-nav-border-top: 0px dotted #ddd;
+}
+
+.dark {
+ /* Axels Overrides */
+ --color-text: #c0c0c0;
+ --link-color: #88e;
+ --brand-color: var(--color-text);
+ --brand-background: var(--body-background);
+ --body-background: #101418;
+ --hr-color: none;
+ --code-tag-background-color_: #bcc;
+ --search-field-background: none;
+ --search-field-border-color: none;
+ --sidebar-background: var(--body-background);
+ --sidebar-border-color: none;
+ --sidebar-link-active-background: #333;
+ /* Axels custom values */
+ --axel_bg-toc: var(--body-background);
+ --axel_bg-toc-head: #333;
+ --axel_brand-background: none;
+ --axel_brand-pre-background: rgb(255, 0, 51);
+ ;
+ --axel_brand-pre-background-hover: rgb(255, 0, 51);
+ ;
+ --axel_h1_header: none;
+ --axel_h1: #578;
+ --axel_h1-bg: none;
+ --axel_h1-bottom: none;
+ --axel_h2: #467;
+ --axel_h2-bg: none;
+ --axel_h2-bottom: 0px solid #256;
+ --axel_h2-hero-bottom: 2px solid #712;
+ --axel_h3: #589;
+ --axel_h3-bottom: 0px solid #333;
+ --axel_hero_bg: #242424;
+ --axel_img-border: 2px dashed #555;
+ --axel_nav-bg: #242424;
+ --axel_nav-buttomborder: #555;
+ --axel_pre-background: #bcc;
+ --axel-th-background: #203038;
+ --axel-article-nav-border-top: 0px dotted #234;
+}
+
+/* ---------- left side ---------- */
+a.Brand::before {
+ background: var(--axel_brand-pre-background);
+ color: #fff;
+ font-family: arial;
+ font-weight: bold;
+ padding: 0.5em 0.3em;
+ content: 'IML';
+ margin-right: 0.4em;
+ float: left;
+}
+
+a.Brand:hover::before {
+ background: var(--axel_brand-pre-background-hover);
+}
+
+a.Brand {
+ background: var(--axel_brand-background);
+ font-size: 200%;
+ height: 4em;
+}
+
+/* ---------- page header: breadcrumb ---------- */
+.Page__header {
+ border: none;
+}
+
+.Page__header a {
+ color: var(--axel_h1_header);
+}
+
+.Page__header h1 {
+ font-size: 1.3em;
+}
+
+/* ---------- page content ---------- */
+.s-content {
+ padding-top: 1em;
+}
+
+.s-content h1 {
+ background: var(--axel_h1-bg);
+ color: var(--axel_h1);
+ font-size: 200%;
+ font-weight: bold;
+ margin-bottom: 2em;
+ margin-top: 2em;
+ border-bottom: var(--axel_h1-bottom);
+}
+
+.s-content h2 {
+ background: var(--axel_h2-bg);
+ color: var(--axel_h2);
+ font-size: 190%;
+ font-weight: bold;
+ margin-top: 4em;
+ border-bottom: var(--axel_h2-bottom);
+}
+
+h1:first-of-type {
+ margin-top: 0em;
+}
+
+h2:first-of-type {
+ margin-top: 0em;
+}
+
+img{
+ border: var(--axel_img-border);
+ border-radius: 1.5em;
+ padding: 0.7em;
+}
+
+.s-content h3 {
+ background: var(--axel_h3-bg);
+ color: var(--axel_h3);
+ font-size: 150%;
+ font-weight: bold;
+ margin-top: 3em;
+ border-bottom: var(--axel_h3-bottom);
+}
+
+
+.s-content > h4 {
+ color: var(--axel_h4);
+ font-size: 135%;
+ font-weight: bold;
+ margin: 2em 0;
+}
+
+.s-content .TableOfContentsContainer h4 {
+ margin: 1em 0;
+ font-size: 110%;
+ text-align: center;
+ background-color: rgba(0, 0, 0, 0.1);
+ padding: 0.3em;
+ font-weight: bold;
+ font-family: Arial;
+}
+ul.TableOfContents a{
+ color: var(--color-text);
+}
+.s-content pre {
+ background: var(--axel_pre-background);
+}
+
+/* FIX smaller fnt size in tables */
+.s-content table {
+ font-size: 1em;
+}
+
+.s-content table th {
+ background: var(--axel-th-background);
+}
+
+.s-content h3 code {
+ border: none;
+ background: none;
+}
+
+article nav {
+ border-top: var(--axel-article-nav-border-top);
+ margin: 8em 0 5em;
+}
+
+.Pager li>a {
+ padding: 1em 2em;
+}
+
+/* ---------- classes ---------- */
+.required {
+ color: #a42;
+}
+
+.optional {
+ color: #888;
+}
+
+div.hero {
+ background: var(--axel_hero_bg);
+ border-radius: 2em;
+ padding: 5em 2em;
+ text-align: center;
+ margin-bottom: 1.5em;
+}
+
+div.hero h2 {
+ color: var(--color-text);
+ background: none;
+ border-bottom: var(--axel_h2-hero-bottom);
+ font-size: 300%;
+ margin: 0 0 2em;
+}
+
+/* ---------- TOC ---------- */
+@media(min-width:1700px) {
+ .TableOfContentsContainer {
+ position: fixed;
+ right: 2em;
+ top: 1em;
+ }
+}
+
+.TableOfContentsContainer {
+ background-color: var(--axel_bg-toc);
+ padding: 0.5em;
+}
+
+.s-content .TableOfContentsContainer h4 {
+ background-color: var(--axel_bg-toc-head);
+ border-top-left-radius: 1em;
+ font-size: 1.1em;
+ margin: 0;
+ padding: 0;
+}
+
+.TableOfContentsContainer__content {
+ border-width: 1px;
+ font-size: 0.5em;
+}
+
+ul.TableOfContents ul {
+ list-style-type: none;
+ padding-left: 1em;
+}
+
+/* ----- Icons on links --- */
+
+.EditOn a::before{
+ content: '✏️ ';
+}
+
+.Links a[href^="https://github.com/"]::before {
+ content: '🌐 ';
+}
+
+.Links a[href^="https://git-repo.iml.unibe.ch/"]::before {
+ content: '🌐 ';
+}
+
+.Links a[href^="https://os-docs.iml.unibe.ch"]::before {
+ content: '📗 ';
+}
--
GitLab