Document the GSSP Fallback feature (#551)

Add comments in the code to link the name of the feature to the internally used "sso registration bypass" for this feature.

Author: pmeulen

docs/MiddlewareConfiguration.md

@@ -414,7 +414,9 @@ The options must have the following keys:
 * `number_of_tokens_per_identity` (integer) The number of tokens an identity is allowed to vet. If the option is not set, the default value of `1` is set.
 * `allowed_second_factors`: (string[]) a list of second factor types that are allowed to be registered by users of this institution. This option only affects the registration of new second factors, it does not affect second factors that have been registered or vetted. If the list is empty all supported second factors are allowed. The supported second factors are found in the [Stepup-bundle](https://github.com/OpenConext/Stepup-bundle/blob/develop/src/Value/SecondFactorType.php#L31-L37). Default: empty list (all available second factors are allowed).
 * `self_vet`: (boolean) Are users allowed to vet their other tokens with a previously vetted token?
+* `allow_self_asserted_tokens`: (boolean) Are users of this institution allowed to register self asserted tokens (SAT)?
 * `sso_on_2fa`: (boolean) Are identities of the institution allowed to use SSO on 2FA?
+* `sso_registration_bypass`: (boolean) Enables or disabled "GSSP fallback" for this institution. Is it allowed for SFO authentications for this institution to "bypass" the Stepup authentication when they have no active tokens, passing the authentication directly to the fallback GSSP (see: fallback_gssp configuration in the gateway).
 
 And optionally the configuration can have these authorization related options:
 

src/Surfnet/Migrations/Version20250501121457.php

@@ -36,6 +36,11 @@ public function up(Schema $schema): void
             'Migration can only be executed safely on \'mysql\'.',
         );
         // Create the new sso_on_2fa option, note the name conversion 'error' made by doctrine.
+        /*
+         * The sso_registration_bypass_option enables and disables the "GSSP fallback" option in the Stepup-Gateway for an institution.
+         * "GSSP fallback" forwards the second factor authentications at LoA 1.5 to the fallback GSSP when a user does not have
+         * any active tokens
+         */
         $this->addSql('ALTER TABLE institution_configuration_options ADD sso_registration_bypass_option INT DEFAULT \'0\' NOT NULL');
         // Create the institution_configuration gateway schema
         $gatewaySchema = $this->getGatewaySchema();

src/Surfnet/Stepup/Configuration/Event/NewInstitutionConfigurationCreatedEvent.php

@@ -66,7 +66,7 @@ public static function deserialize(array $data): self
         if (!isset($data['sso_on_2fa_option'])) {
             $data['sso_on_2fa_option'] = false;
         }
-        // If sso registration bypass option is not yet present, default to false
+        // If GSSP fallback (sso registration bypass) option is not yet present, default to false
         if (!isset($data['sso_registration_bypass_option'])) {
             $data['sso_registration_bypass_option'] = false;
         }
@@ -86,7 +86,7 @@ public static function deserialize(array $data): self
             new VerifyEmailOption($data['verify_email_option']),
             new NumberOfTokensPerIdentityOption($data['number_of_tokens_per_identity_option']),
             new SsoOn2faOption($data['sso_on_2fa_option']),
-            new SsoRegistrationBypassOption($data['sso_registration_bypass_option']),
+            new SsoRegistrationBypassOption($data['sso_registration_bypass_option']),   // Fallback authentication
             new SelfVetOption($data['self_vet_option']),
             new SelfAssertedTokensOption($data['self_asserted_tokens_option']),
         );

src/Surfnet/Stepup/Configuration/Event/SsoRegistrationBypassOptionChangedEvent.php

@@ -25,6 +25,11 @@
 use Surfnet\Stepup\Configuration\Value\InstitutionConfigurationId;
 use Surfnet\Stepup\Configuration\Value\SsoRegistrationBypassOption;
 
+/*
+ * This option enables and disables the "GSSP fallback" option in the Stepup-Gateway for an institution.
+ * "GSSP fallback" forwards the second factor authentications at LoA 1.5 to the fallback GSSP when a user does not have
+ * any active tokens
+ */
 final class SsoRegistrationBypassOptionChangedEvent implements SerializableInterface
 {
     public function __construct(

src/Surfnet/Stepup/Configuration/Value/SsoRegistrationBypassOption.php

@@ -22,6 +22,12 @@
 
 use JsonSerializable;
 
+/*
+ * The SsoRegistrationBypassOption is the "GSSP fallback" option in the Stepup-Gateway for an institution that
+ * forwards the second factor authentications at LoA 1.5 to the fallback GSSP when a user does not have
+ * any active tokens
+ */
+
 final readonly class SsoRegistrationBypassOption implements JsonSerializable
 {
     public static function getDefault(): self

src/Surfnet/StepupMiddleware/ApiBundle/Doctrine/Type/SsoRegistrationBypassOptionType.php

@@ -26,6 +26,10 @@
 
 /**
  * Custom Type for the SsoRegistrationBypassOption Value Object
+ *
+ * This option enables and disables the "GSSP fallback" option in the Stepup-Gateway for an institution.
+ * "GSSP fallback" forwards the second factor authentications at LoA 1.5 to the fallback GSSP when a user does not have
+ * any active tokens
  */
 class SsoRegistrationBypassOptionType extends IntegerType
 {

src/Surfnet/StepupMiddleware/GatewayBundle/Entity/InstitutionConfiguration.php

@@ -36,7 +36,7 @@ public function __construct(
         #[ORM\Column(type: 'boolean')]
         public bool $ssoOn2faEnabled,
         /**
-         * @var bool is the SSO registration bypass feature enabled?
+         * @var bool is the GSSP fallback (SSO registration bypass) feature enabled?
          */
         #[ORM\Column(type: 'boolean')]
         public bool $ssoRegistrationBypass,