====== MFA ======

<WRAP alert>
**Dokument je zatím stále v přípravě. V žádném případě toto nastavení neprovádějte na produkčním IdP!**
</WRAP>

Tento dokument popisuje zprovoznění dvoufaktorového ověřování na straně Shibboleth IdP a zavedení podpory pro [[https://refeds.org/profile/mfa|profil REFEDS MFA]]. Jsou zde popsány konfigurační kroky na straně IdP a také je zde ukázka pro rozšíření LDAP schématu o atribut, do kterého je nutné uložit "seedu" pro TOTP.

Vše, co je zde sepsáno, vychází z následujících oficiálních dokumentů:
  * [[https://shibboleth.atlassian.net/wiki/spaces/KB/pages/1474297850/Supporting+the+REFEDS+MFA+Profile|Supporting the REFEDS MFA Profile]]
  * [[https://shibboleth.atlassian.net/wiki/spaces/IDP4/pages/1265631610/MultiFactorAuthnConfiguration|MultiFactorAuthnConfiguration]]
  * [[https://shibboleth.atlassian.net/wiki/spaces/IDPPLUGINS/pages/1376878877/TOTP|TOTP]]


===== Modul MFA =====

Jako první krok je zapnutí modulu MFA v IdP:

<code bash>
cd /opt/shibboleth-idp
./bin/module.sh -e idp.authn.MFA
</code>

Nyní je potřeba provést úpravy v konfiguračním souboru pro autentizaci, tedy v //conf/authn/authn.properties//:

<code bash>
vim conf/authn/authn.properties
</code>

Nastavení toku (idp.authn.flows) na MFA a přidání podpory pro profil REFEDS MFA:

<code ini>
idp.authn.flows = MFA

idp.authn.MFA.supportedPrincipals = \
    saml2/https://refeds.org/profile/mfa, \
    saml2/urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport, \
    saml2/urn:oasis:names:tc:SAML:2.0:ac:classes:Password, \
    saml1/urn:oasis:names:tc:SAML:1.0:am:password

idp.authn.TOTP.supportedPrincipals = \
    saml2/https://refeds.org/profile/mfa, \
    saml2/urn:oasis:names:tc:SAML:2.0:ac:classes:TimeSyncToken
</code>

Dále upravíme v konfiguračním souboru //conf/authn/mfa-authn-config.xml// MFA:

<code bash>
vim conf/authn/mfa-authn-config.xml
</code>

Níže uvedený kód způsobí, že uživatel je při autentizaci vyzván k zadání svého uživatelského jména a hesla. Pokud jsou zadané údaje správné a služba vyžaduje dvoufaktorové ověření, je uživateli předložena žádost o ověření druhého faktoru. Pokud služba doufaktorové ověření nepotřebuje, bude uživatel po zadání správného jména a hesla přesměrován na službu, aniž by musel řešit druhý faktor:

<code xml>
<util:map id="shibboleth.authn.MFA.TransitionMap">
    <!-- First rule runs the Password login flow. -->
    <entry key="">
        <bean parent="shibboleth.authn.MFA.Transition" p:nextFlow="authn/Password" />
    </entry>

    <!--
    Second rule runs a function if Password succeeds, to determine whether an additional
    factor is required.
    -->
    <entry key="authn/Password">
        <bean parent="shibboleth.authn.MFA.Transition" p:nextFlowStrategy-ref="checkSecondFactor" />
    </entry>
</util:map>

<!-- Example script to see if second factor is required. -->
<bean id="checkSecondFactor" parent="shibboleth.ContextFunctions.Scripted" factory-method="inlineScript">
    <constructor-arg>
        <value>
        <![CDATA[
            nextFlow = "authn/TOTP";

            // Check if second factor is necessary for request to be satisfied.
            authCtx = input.getSubcontext("net.shibboleth.idp.authn.context.AuthenticationContext");
            mfaCtx = authCtx.getSubcontext("net.shibboleth.idp.authn.context.MultiFactorAuthenticationContext");
            if (mfaCtx.isAcceptable()) {
                nextFlow = null;
            }
                
            nextFlow;   // pass control to second factor or end with the first
        ]]>
        </value>
    </constructor-arg>
</bean>
</code>

===== Rozšíření TOTP =====

Druhý krok na IdP je zapnutí rozšíření TOTP, které je součástí projektu Shibboleth IdP.

<code bash>
cd /opt/shibboleth-idp
./bin/plugin.sh -I net.shibboleth.idp.plugin.authn.totp
</code>

Dále je potřeba definovat, ve kterém atributu je v LDAPu uložen tzv. "TOTP seed", na jehož základě se počítá časově omezený jednorázový kód.

<code bash>
vim conf/attribute-resolver.xml
</code>

Atribut se může jmenovat libovolně, nicméně důrazně doporučujeme použít atribut nazvaný ''tokenSeeds'', protože to je výchozí hodnota definovaná v Shibbolethu. Pokud se atribut jmenuje jinak, je nutná dodatečná konfigurace IdP a to považujeme za zbytečné.

<code xml>
<AttributeDefinition xsi:type="Simple" id="tokenSeeds">
    <InputDataConnector ref="myLDAP" attributeNames="tokenSeeds"/>
</AttributeDefinition>
</code>

Restartováním Jetty zajistíme nahrání nové konfigurace IdP:

<code bash>
systemctl restart jetty9
</code>

===== Atribut tokenSeeds v LDAP serveru =====

V LDAP serveru musí být dostupný výše uvedený atribut ''tokenSeeds'', který obsahuje "seed" pro TOTP.

Definice atributu ''tokenSeeds'' v rámci schématu:

<code ldif>
attributeTypes: ( tokenSeeds-oid
  NAME 'tokenSeeds'
  DESC 'TOTP Seed'
  SYNTAX 1.3.6.1.4.1.1466.115.121.1.26
  SINGLE-VALUE
  X-ORIGIN 'CESNET'
 )
</code>

Atribut ''tokenSeeds'' definujeme ve schématu jako volitelný, proto je potřeba umístit ho do "MAY":

<code ldif>
objectClasses: ( tenOrgPerson-oid
   NAME 'tenOrgPerson'
   SUP top STRUCTURAL
   MAY ( aci $
         tokenSeeds $
         cesnetEmplID $
         authorisedMail $
         rfc822ForwardingMailbox $
         memberOf )
   X-ORIGIN 'cesnet.cz'
 )
</code>

===== Testování =====

Pro testování vícefaktorového ověřování na IdP je dostupná služba na serveru [[https://mfa.eduid.cz|mfa.eduid.cz]].

===== Vyžadování MFA na službě =====

[[https://shibboleth.atlassian.net/wiki/spaces/SP3/pages/2114781453/Requiring+Multi-Factor+Authentication|Dokumentace]] k vyžadování MFA na webu projektu Shibboleth.