Skip to content

Home

Jump to bottom
disisto edited this page Nov 6, 2023 · 7 revisions

SimpleSAMLphp Bootstrap Theme

SimpleSAMLphp Bootstrap Theme is a child theme for SimpleSAMLphp that outputs certain visitor facing pages via Bootstrap front-end framework. Intended to deliver a seamless look and feel when the visitor already comes from a project based on a Bootstrap layout.

Content

Requirements

  • SimpleSAMLphp 2.0 or 2.1
  • Bootstrap 5.3*

*Needed files are already included in this project.

Installation

When authentication occurs, the visitor is redirected to the Identity Provider (IdP) for login. Therefore, upload the bootstrap folder and its contents into the module folder on your IdP.

/var/simplesamlphp/modules/

This is the default installation path. If your path is different, select the appropriate path.

Download

Let's download, unzip and move the needed files to it's destination. Choose the tool you prefer.

cURL

Open the right path:
cd /var/simplesamlphp/modules/

Download the repository via cURL
sudo curl -LJO https://github.com/disisto/simplesamlphp-bootstrap-theme/archive/refs/heads/main.zip

Unzip the downloaded repository
sudo unzip simplesamlphp-bootstrap-theme-main.zip

Move the desired folder to the correct path
sudo mv simplesamlphp-bootstrap-theme-main/bootstrap .

Delete the unnecessary files
sudo rm -R simplesamlphp-bootstrap-theme-main*

wget

Open the right path:
cd /var/simplesamlphp/modules/

Download the repository via wget
sudo wget https://github.com/disisto/simplesamlphp-bootstrap-theme/archive/refs/heads/main.zip

Unzip the downloaded repository
sudo unzip main.zip

Move the desired folder to the correct path
sudo mv simplesamlphp-bootstrap-theme-main/bootstrap .

Delete the unnecessary files
sudo rm -R simplesamlphp-bootstrap-theme-main/ main*

git

Open the right path:
cd /var/simplesamlphp/modules/

Download the repository via git
sudo git clone https://github.com/disisto/simplesamlphp-bootstrap-theme.git

Move the desired folder to the correct path
sudo mv simplesamlphp-bootstrap-theme/bootstrap .

Delete the unnecessary files
sudo rm -R simplesamlphp-bootstrap-theme

Enable Theme

In order to enable the theme, we need to adjust the config.php and adjust the following entry:

File: /var/simplesamlphp/config/config.php

from:

    'module.enable' => [
        'exampleauth' => false,
        'core' => true,
        'admin' => true,
        'saml' => true
    ],

to

    'module.enable' => [
        'bootstrap' => true,
        'exampleauth' => false,
        'core' => true,
        'admin' => true,
        'saml' => true
    ],

This can be done comfortably with the stream editor sed.

Enable theme: sed -i "/ 'module.enable' => \[/a\ 'bootstrap' => true," /var/simplesamlphp/config/config.php

Disable theme: sudo sed -i "/'bootstrap' => true/d" /var/simplesamlphp/config/config.php

Switch Theme

In order to select the desired theme, we need to adjust the config.php and adjust the following entry:

File: /var/simplesamlphp/config/config.php

'theme.use' => 'default', to

'theme.use' => 'bootstrap:5',

This can be done comfortably with the stream editor sed.

Enable theme: sudo sed -i "s/'theme\.use' => 'default',/'theme\.use' => 'bootstrap:5',/" /var/simplesamlphp/config/config.php

Disable theme: sudo sed -i "s/'theme\.use' => 'bootstrap:5',/'theme\.use' => 'default',/" /var/simplesamlphp/config/config.php

Congratulations! 🎉 If you now request the login prompt, you will see that the template is in use. Let's do some customization in the next chapter.

Customization

When you open the login page for the first time, you have the desire to make changes in three areas:

1.) The Favicon


2.) The Logo
3.) The Copyright (footer)

All changes can be made in a single file:

/var/simplesamlphp/modules/bootstrap/themes/5/default/bootstrap.twig

You will notice that in the first lines consists mostly of comments. These explain how the changes should look. Here they are explained again.

Favicon

If you do not want a favicon, you have two options:

Option A) Remove the following line from the script:

{% set favicon = asset("vendor/bootstrap/5.3.1/img/favicon.ico", 'bootstrap') %}

Option B) Set the value to NULL. Replace the existing line with the following line:

{% set favicon = null %}

If you want to replace the favicon, you have two options:

Option A)

  • Upload your favicon to /var/simplesamlphp/modules/bootstrap/public/assets/
  • Adjust the path in the script: {% set favicon = asset("favicon.ico", 'bootstrap') %}

Option B)

  • Your favicon is located on another publicly accessible server.
  • Replace the path with the desired URL: {% set favicon = 'https://getbootstrap.com/docs/5.3/assets/img/favicons/favicon.ico' %}

Logo

If you do not want a logo, you have two options:

Option A) Remove the following line from the script:

{% set logo = asset("vendor/bootstrap/5.3.1/img/bootstrap-logo.svg", 'bootstrap') %}

Option B) Set the value to NULL. Replace the existing line with the following line:

{% set logo = null %}

If you want to replace the logo, you have two options:

Option A)

  • Upload your logo to /var/simplesamlphp/modules/bootstrap/public/assets/
  • Adjust the path in the script: {% set logo = asset("logo.png", 'bootstrap') %}

Option B)

  • Your favicon is located on another publicly accessible server.
  • Replace the path with the desired URL: {% set logo = 'https://getbootstrap.com/docs/5.3/assets/brand/bootstrap-logo.svg' %}

Copyright (Footer)

The copyright (footer) consists of two independent parts. The year and signature. You have the choice to enable/disable both or one of them.

Year specification

If you do not want a year specification, you have two options:

Option A) Remove the following line from the script:

{% set copyrightyear = year %}

Option B) Set the value to NULL. Replace the existing line with the following line:

{% set copyrightyear = null %}

If you want to show a year specification, you have two options:

Option A) Show just the current year

  • You do not need to change anything. This is already the default setting.

Option B) Show a time range, e.g. since establishment to current year (like © 2011-2023)

  • Set the as follow:
    -- Replace 2011 with your desired year.
    {% set copyrightyear = '2011-' ~ year %}

In case you don't want any dynamic changes you can hardcode the time range:
{% set copyrightyear = '2011-2018' %}

Signature specification

If you do not want a signature specification, you have two options:

Option A) Remove the following line from the script:

{% set copyrightsignature = null %}

Option B) Leave the value on NULL. This is already the default setting.

{% set copyrightyear = null %}

If you want to show a signature specification, replace the following entry with the desired entry.
In this example the 'The Bootstrap Authors' is set as entry.
{% set copyrightsignature = 'The Bootstrap Authors' %}

Individual design

Publicly accessible pages

Page Files Folder URL
Welcome welcome.twig /modules/bootstrap/themes/5/core /module.php/core/welcome
Login loginuserpass.twig /modules/bootstrap/themes/5/core /module.php/core/loginuserpass?AuthState=$1
Error error.twig /modules/bootstrap/themes/5/default /module.php/core/loginuserpass
Contact form confirmation message errorreport.twig /modules/bootstrap/themes/5/core /module.php/core/errorReport

Then we have some common elements:

File Folder Definition
bootstrap.twig /modules/bootstrap/themes/5/default The bootstrap.twig is the beginning of everything. This file contains the basic HTML framework (head, body) and links everything together.
_bootstrap_header.twig /modules/bootstrap/themes/5/default The _bootstrap_header.twig is the (invisible) navbar that contains the dropdown menu for language selection and color modes.
_footer.twig /modules/bootstrap/themes/5/default This slightly changes only the footer in the admin area. Can be deleted as it has no relevance for this project.

As you will see the Twig template engine is still used and is still responsible for delivering the content. No hack has been done at this point. Only the CSS class names have been replaced to the Bootstrap stylesheets to maintain the look and feel. All pages in the admin area were not considered.

File Folder Definition
sign-in.css /modules/bootstrap/public/assets/css/ Apart from the height setting for the attribute html/body, includes adjustments for login, header and error page.
bootstrap.five.copyToClipboard.js /modules/bootstrap/public/assets//js/ Enables the copy to clipboard function for a button in the error.twig.

  ⚠️ The bootstrap.twig refers to minified version of the above files. Make changes to both files or refer to the regular/non-minified version.
  ⚠️ Don't forget to clear your browser cache before examining the changes.

Enjoy! 🙌

This project is not affiliated with SimpleSAMLphp, Twig and/or Bootstrap.
All mentioned trademarks are the property of their respective owners.

Clone this wiki locally