Merge pull request #11 from OpenConext/misc-textual-improvements

Misc textual improvements

README.md

@@ -7,6 +7,48 @@ Stepup-gssp-example
 
 Example Generic SAML Stepup Provider.
 
+This repository can be used for reference material or 
+as a base project setup for new IdP SecondFactor application.
+
+The SAML logic for receiving authentication request (AuthnRequest) and sending authentication response back is
+placed inside the Symfony bundle [stepup-gssp-bundle](https://github.com/OpenConext/Stepup-gssp-bundle). The state of the
+application is stored inside PHP sessions, each new request will invalidate the current session state.
+
+Locale user preference
+----------------------
+
+The default locale is based on the user agent. When the user switches its locale the selected preference is stored inside a
+browser cookie (stepup_locale). The cookie is set on naked domain of the requested domain (for gssp.stepup.example.com this is example.com).
+
+Authentication and registration flows
+-------------------------------------
+
+The application provides internal (SpBundle) and a remote service provider. Instructions for this are given 
+on the homepage of this example project [Homepage](https://gssp.stepup.example.com/app_dev.PHP/).
+
+![flow](docs/flow.png)
+<!---
+regenerate docs/flow.png with `plantum1 README.md` or with http://www.plantuml.com/plantuml
+@startuml docs/flow
+actor User
+participant "Service provider" as SP
+box "Stepup GSSP example"
+participant "GSSP Bundle" as IdP
+participant "SecondFactor implementation" as App
+end box
+User -> SP: Register/Authenticate
+SP -> IdP: Send AuthnRequest
+activate IdP
+IdP -> App: Redirect to SecondFactor endpoint
+App -> App: <Your custom SecondFactor implementation>
+App -> IdP: Redirect to SSO Return endpoint
+IdP -> SP: AuthnRequest response
+deactivate IdP
+SP -> User: User registered/Authenticated
+@enduml
+--->
+
+
 How to create your own Stepup Provider
 ======================================
 
@@ -70,8 +112,6 @@ Install composer dependencies:
 
 Build frond-end assets:
 
-``` composer install ```
-
 ``` composer encore dev ``` or ``` composer encore prod ``` for production 
 
 If everything goes as planned you can go to:

app/AppKernel.php

@@ -22,11 +22,11 @@ public function registerBundles()
             $bundles[] = new Symfony\Bundle\DebugBundle\DebugBundle();
             $bundles[] = new Symfony\Bundle\WebProfilerBundle\WebProfilerBundle();
             $bundles[] = new Sensio\Bundle\DistributionBundle\SensioDistributionBundle();
+            $bundles[] = new SpBundle\SpBundle();
 
             if ('dev' === $this->getEnvironment()) {
                 $bundles[] = new Sensio\Bundle\GeneratorBundle\SensioGeneratorBundle();
                 $bundles[] = new Symfony\Bundle\WebServerBundle\WebServerBundle();
-                $bundles[] = new SpBundle\SpBundle();
             }
         }
 

app/Resources/translations/messages.en.yml

@@ -15,14 +15,14 @@ page.navigation.route.sp_demo: Demo SP
 
 page.footer.terms: Terms and Conditions
 
-page.index.title: Welcome to Generic SAML Stepup Provider SDK
+page.index.title: Welcome to the Generic SAML Stepup Provider SDK
 page.index.body.intro: |
-  Your application is ready. You can use this example to start imlementing your authentication.
-  SDK is configured with demo configuration and can provide registration and authentication to the demo SP.
+  The application is ready for use. This example project can be used to develop your own implemention of a GSSP verification method.
+  It demonstrates registration and authentication of second factor tokens initiated by a dummy service provider.
 
 page.index.body.sdk_discription: |
-  The AppBundle contains the example registration and authentication endpoints. This is the main entry for your application. See DefaultController::registrationAction and DefaultController::authenticateAction.
-  This is the place to implement the logic of your IdP. For more information read the README.md file of this project.
+  This Symfony Framework application contains an AppBundle where the example registration and authentication endpoints are implemented. This is the main entry of the application. See DefaultController::registrationAction and DefaultController::authenticateAction.
+  This is the place to implement the logic of the GSSP identity provider. For more information read the README.md file of this project.
 
 page.index.external_sp: External service provider
 page.index.internal_sp: Internal service provider
@@ -36,7 +36,7 @@ page.index.body.registration.external.step4.click_register: 4) Click the 'Regist
 page.index.body.authentication.title: Authentication flow
 page.index.body.authentication.external.step1.go_to_sp: 1) Go to
 page.index.body.authentication.external.step2.select_idp: 2) Select '%idp-entity-id%' from the 'Identity Provide' list
-page.index.body.authentication.external.step3.fill_subject: 3) Fill the user NameId in the 'subject' field
+page.index.body.authentication.external.step3.fill_subject: 3) Fill in the user NameId in the 'subject' field
 page.index.body.authentication.external.step4.click_login: 4) Click the 'login' button
 page.index.body.authentication.external.step5.click_authenticate: 5) Click the 'Authenticate user' button
 
@@ -45,32 +45,31 @@ page.index.body.registration.internal.step2.click_login: 2) Click the 'login' bu
 page.index.body.registration.internal.step3.click_register: 3) Click the 'Register user' button
 
 page.index.body.authentication.internal.step1.go_to_sp: 1) Go to
-page.index.body.authentication.internal.step2.fill_subject: 2) Fill the user NameId in the 'nameId' field
+page.index.body.authentication.internal.step2.fill_subject: 2) Fill in the user NameId in the 'nameId' field
 page.index.body.authentication.internal.step3.click_login: 3) Click the 'login' button
 page.index.body.authentication.internal.step4.click_authenticate: 4) Click the 'Authenticate user' button
 
 page.route.description.documentation_purpose: |
-  This path is linked in the menu for demo and documentation purpose.
+  This path is linked in the menu for demo and documentation purposes.
 
 page.route.description.app_identity_registration: |
-  The application path that handles the registration, this is the entry point to implement the custom registration logic.
+  The application path that handles registration, custom registration logic is implemented here.
 
 page.route.description.app_identity_authentication: |
-  The application path that handles the authentication, this is the entry point to implement the custom authentication logic.
+  The application path that handles authentication, custom authentication logic is implemented here.
 
 page.route.description.gssp_saml_sso: >
-  It's provided by the GSSP bundle that handles the AuthnRequest saml request from Service Provider.
-  Then it decides if it needs to go to the application registration path or application authentication path.
+  The user is redirected to this URL where the SAML AuthnRequest is handled by offering the user either registration or authentication.
 
 page.route.description.gssp_saml_sso_return: |
-  It's provided by the GSSP bundle that handles the saml response back to the Service provider.
+  The user is redirected to this URL after completing authentication or registration within the GSSP application. The user is then redirected back to the service provider with a SAML response.
 
-  - If the application expects a registration or authentication but the user is not yet registered or authenticated by the application, the user will be redirected back to the corresponding path.
+  - If the application expects registration or authentication but the user is not yet registered or authenticated by the application, the user will be redirected back to the corresponding path.
   - Shows a submit button when JavaScript is disabled
 
 page.route.description.sp_demo: |
   Demo service provider to test the second factor IdP application with.
-  This is not part of the second factor IdP and can only be used in development mode.
+  This is not part of the second factor IdP and can only be used in development (app_dev.php) mode.
 
 en: EN
 nl_NL: NL

app/Resources/translations/messages.nl.yml

@@ -17,12 +17,12 @@ page.footer.terms: Algemene voorwaarden
 
 page.index.title: Welkom bij Generieke SAML Stepup Provider SDK
 page.index.body.intro: |
-    U applicatie is klaar voor gebruik. U kunt dit voorbeeld gebruiken om uw verificatie te implementeren.
-    SDK is geconfigureerd met demo-configuratie en kan registratie en authenticatie bieden voor een service provider.
+    De applicatie is klaar voor gebruik. Dit voorbeeldproject kan gebruikt worden om een eigen implementatie van een GSSP verificatiemiddel te ontwikkelen.
+    Het demonstreert registratie en authenticatie van second factor tokens geïnitieerd door een dummy service provider.
 
 page.index.body.sdk_discription: |
-    De AppBundle bevat de voorbeeldregistratie en verificatie-endpoints. Dit is het hoofddoel voor uw toepassing. Zie DefaultController::registrationAction en DefaultController::authenticateAction.
-    Dit is de plaats om de logica van u IdP te implementeren. Lees voor meer informatie de README.md van dit project.
+    Deze Symfony Framework applicatie bestaat uit een AppBundle waar de voorbeeld registratie- en verificatie-endpoints zijn geïmplementeerd. Dit is het startpunt van de applicatie. Zie DefaultController::registrationAction en DefaultController::authenticateAction.
+    Dit is de plaats om de logica van de GSSP identity provider te implementeren. Lees voor meer informatie de README.md van dit project.
 
 page.index.external_sp: External service provider
 page.index.internal_sp: Internal service provider
@@ -41,28 +41,27 @@ page.index.body.authentication.external.step4.click_login: 4) Klik op de knop 'A
 page.index.body.authentication.external.step5.click_authenticate: 5) Klik op de knop 'Gebruiker verifiëren'
 
 page.index.body.registration.internal.step1.go_to_sp: 1) Ga naar
-page.index.body.registration.internal.step2.click_login: 2) Klik op de knop 'Registreer gebruiker'
-page.index.body.registration.internal.step3.click_register: 3) Klik op de knop 'Gebruiker registreren'
+page.index.body.registration.internal.step2.click_login: 2) Klik op de knop 'Registreer gebruiker' van de interne service provider
+page.index.body.registration.internal.step3.click_register: 3) Klik op de knop 'Gebruiker registreren' van de sterke authenticatie IdP
 
 page.index.body.authentication.internal.step1.go_to_sp: 1) Ga naar
 page.index.body.authentication.internal.step2.fill_subject: 2) Vul de subject NameId in het veld 'Subject NameID' in
-page.index.body.authentication.internal.step3.click_login: 3) Klik op de knop 'Gebruiker verifiëren'
-page.index.body.authentication.internal.step4.click_authenticate: 4) Klik op de knop 'Gebruiker verifiëren'
+page.index.body.authentication.internal.step3.click_login: 3) Klik op de knop 'Gebruiker verifiëren' van de interne service provider
+page.index.body.authentication.internal.step4.click_authenticate: 4) Klik op de knop 'Gebruiker verifiëren' van de sterke authenticatie IdP
 
 page.route.description.documentation_purpose: |
-    Deze url is in het menu gekoppeld voor demo en documentatie doeleinden.
+    Deze url is in het menu gekoppeld voor demo- en documentatiedoeleinden.
 
 page.route.description.app_identity_registration: |
-    Het applicatiepad dat de registratie afhandelt, dit is het startpunt om de aangepaste registratielogica te implementeren.
+    Het applicatiepad dat de registratie afhandelt, eigen registratielogica wordt hier geïmplementeerd.
 page.route.description.app_identity_authentication: |
-    Het applicatiepad dat de authenticatie afhandelt, dit is het toegangspunt om de aangepaste authenticatielogica te implementeren.
+    Het applicatiepad dat de authenticatie afhandelt, eigen authenticatielogica wordt hier geïmplementeerd.
 page.route.description.gssp_saml_sso: |
-    Het wordt geleverd door de GSSP-bundel die de aanvraag AuthnRequest SAML van de serviceprovider afhandelt.
-    Vervolgens bepaalt het of het naar het registratiepad van de toepassing of het pad voor toepassingsverificatie moet gaan.
+    De gebruiker wordt naar deze URL gestuurd waar het SAML AuthnRequest  wordt afgehandeld door de gebruiker registratie of authenticatie aan te bieden.
 page.route.description.gssp_saml_sso_return: |
-    Het wordt geleverd door de GSSP-bundel die de SAML-response afhandelt naar de serviceprovider.
+    De gebruiker wordt naar deze URL gestuurd na het afronden van registratie of authenticatie binnen de GSSP-applicatie. De gebruiker wordt hierna teruggestuurd naar de service provider met een SAML response.
 
-    - Als de toepassing een registratie of verificatie verwacht maar de gebruiker nog niet is geregistreerd of geverifieerd door de toepassing, wordt de gebruiker teruggeleid naar het desbetreffende pad.
+    - Als registratie of authenticatie wordt verwacht maar de gebruiker nog niet is geregistreerd of geauthenticeerd door de applicatie, wordt de gebruiker teruggeleid naar het desbetreffende pad.
     - Toont een submit button als JavaScript is uitgeschakeld
 page.route.description.sp_demo: |
     Demo url voor het ontvangen van de SAML AuthnRequest response van de IdP.

docs/index.md

@@ -1,4 +1,3 @@
 # Documentation
 
-1. [Architecture](architecture.md)
-2. [Testing](testing.md)
+1. [Testing](testing.md)

docs/testing.md

@@ -1,9 +1,8 @@
 # Testing
 
-Because of the chosen [architecture](architecture.md) we have the ability to test different parts of the code in
-isolation. This allows for a test suite that runs very fast, and can therefore be run very often, keeping the feedback
-loop as short as possible. The test suite can also be executed locally as well as on a continuous integration server,
-which also helps the developer to get feedback as quickly as possible.
+Different parts of the code can be tested in isolation. This allows for a test suite that runs very fast, and can
+therefore be run very often, keeping the feedback loop as short as possible. The test suite can also be executed locally
+as well as on a continuous integration server, which also helps the developer to get feedback as quickly as possible.
 
 You can run all test combined with:
 

tests/AppBundle/Controller/DefaultControllerTest.php

@@ -28,6 +28,6 @@ public function testIndex()
         $crawler = $client->request('GET', '/');
 
         $this->assertEquals(200, $client->getResponse()->getStatusCode());
-        $this->assertContains('Welcome to Generic SAML Stepup Provider SDK', $crawler->filter('h2')->text());
+        $this->assertContains('Welcome to the Generic SAML Stepup Provider SDK', $crawler->filter('h2')->text());
     }
 }