Guide
TrainingSupportCommunity

Shibboleth

Suggest Edits

If you're using Shibboleth as your identity management system, you can integrate it with ​Akamai MFA​ to provide an additional layer of protection for your on-premises, mobile, and third-party cloud applications. With this integration, all login requests are sent to Shibboleth IdP and redirected to ​Akamai MFA​.

See this diagram that presents a conceptual model of the authentication process. For clarity reasons, some traffic flows are not covered.

📘

This authentication process refers to users who are enrolled in ​Akamai MFA​.

  1. The user attempts to access a protected enterprise application.

  2. The user is prompted to log in using their credentials.

  3. Upon successful authentication, Shibboleth IdP, using the ​Akamai​ plug-in, establishes a connection over TCP port 443 and redirects the user to ​Akamai MFA​.

  4. ​Akamai MFA​ challenges the user with secondary authentication.

  5. The user confirms their identity using the selected secondary authentication method.

  6. ​Akamai MFA​ redirects the user to the Shibboleth IdP.

  7. Shibboleth IdP redirects the user to the application server.

  8. The user gains access to the application.

ag-shibboleth-diagram

Before you begin

  • This integration has been tested on Shibboleth versions 4.0.1 and 4.2. Make sure to follow the relevant installation guide, depending on the version you're using.

  • This integration communicates with ​Akamai MFA​ on TCP port 443. Make sure that your firewall allows outbound connections to the host you specify when you set up the integration. You can achieve this by setting up a firewall policy that allows connections to the appropriate CIDR (Classless Inter-Domain Routing) blocks. The following csv file provides the relevant CIDR blocks for the ​mfa.akamai.com​ host: ​Akamai MFA​ CIDR blocks list.

📘

Your <API Host> is available on the ​Akamai MFA​ Integrations configuration page.

Add Shibboleth as an integration

Follow this procedure to generate your integration credentials that you will need to provide in the following step to enable the communication between ​Akamai MFA​ and Shibboleth.

  1. In the Enterprise Center navigation menu, select Multi-factor Authentication > Integrations.

  2. Click Add integration (+).

  3. In Integration Type, select Shibboleth.

  4. In Name, enter a unique name for your Shibboleth integration.

  5. Click Save and Deploy.
    You’ve just generated your API Host, Integration ID, Verifying Key, and Signing Key. This data will be available for you on the integration page. Your integration credentials can be copied anytime and used in the following steps to configure the integration with Shibboleth.

📘

Your Signing Key should be kept completely secret like any other password or secret key credential.

Installation of the ​Akamai MFA​ plugin for Shibboleth 4.1 or later

Follow these steps to install the Shibboleth plugin for ​Akamai MFA​. With this installation, you enable both sides of the integration to communicate with each other.

📘

$IDP_HOME is the path to the Shibboleth installation on the server machine.

  1. Download the AkamaiMfaShibboleth-latest.tgz package and extract its contents.

  2. Copy these files into the Shibboleth installation directory and merge content into any existing files:

📘

If you are upgrading from an older version of the plugin, make sure that you replace the prior Shibboleth plugin files.

  • shibboleth-idp/conf/global.xml into $IDP_HOME/conf/global.xml

    • Bean definition for the authn/AkamaiMfa flow.

  • shibboleth-idp/conf/authn/ into $IDP_HOME/conf/authn/

  • shibboleth-idp/edit-webapp/WEB-INF/lib/ into $IDP_HOME/edit-webapp/WEB-INF/lib/

  • shibboleth-idp/flows/authn/AkamaiMfa/ into $IDP_HOME/flows/authn/AkamaiMfa/

    • The directory name is case sensitive and gets mapped to the authn/AkamaiMfa flow.

  • shibboleth-idp/messages/ into $IDP_HOME/messages/

  • shibboleth-idp/views/ into $IDP_HOME/views/

  • shibboleth-idp/webapp/js/ into $IDP_HOME/webapp/js/

    • Destination may be $IDP_HOME/dist/webapp/js when using the dist prefix.

  1. Update $IDP_HOME/conf/authn/akamaimfa.properties with values from the ​Akamai MFA​ Shibboleth integration:

    • akamaimfa.apiHost. This refers to the API Host that you copied from the ​Akamai MFA​ integration page.
    • akamaimfa.allowedOrigins. Comma-separated list of allowed origins for the IDP. This allows all known virtual hosts to be supported.
      For example: akamaimfa.allowedOrigins = https://idphostname1.com, https://idphostname2.com
    • akamaimfa.callbackUrl. Override the IDP hostname with a specific callback URL origin. Remove or comment out this line to allow dynamic callback URL origins based on akamaimfa.allowedOrigins.
    • akamaimfa.appId. This refers to the Integration ID that you copied from the ​Akamai MFA​ integration page.
    • akamaimfa.signingKey. This refers to the Signing Key that you copied from the ​Akamai MFA​ integration page.
    • akamaimfa.verifyingKey. This refers to the Verifying Key that you copied from the ​Akamai MFA​ integration page.
    • To configure multiple Shibboleth integrations within your tenant, add the following:
      • akamaimfa.isUserIdentifierApplicable = true. This enables support for multiple integrations in the plugin.
      • Specify each integration as an indexed entry under akamaimfa.userIdentifier, starting from 0 for the first integration. For example: 
        akamaimfa.userIdentifier[0].identifier = abc.com  
akamaimfa.userIdentifier[0].appId = 456  
akamaimfa.userIdentifier[0].signingKey = signing-key-abc  
akamaimfa.userIdentifier[0].verifyingKey = verifying-key-abc

        akamaimfa.userIdentifier[1].identifier = xyz.com
akamaimfa.userIdentifier[1].appId = 789
akamaimfa.userIdentifier[1].signingKey = signing-key-xyz
akamaimfa.userIdentifier[1].verifyingKey = verifying-key-xyz
        Continue the pattern for additional integrations, incrementing the index each time.

  2. Update the <util:map id="shibboleth.authn.MFA.TransitionMap"> element in $IDP_HOME/conf/authn/mfa-authn-config.xml:

  • For an authentication that is password-based in the first step and followed by the ​Akamai MFA​ second factor:
<util:map id="shibboleth.authn.MFA.TransitionMap">
  <entry key="">
    <bean parent="shibboleth.authn.MFA.Transition" p:nextFlow="authn/Password" />
  </entry>
  <entry key="authn/Password">
    <bean parent="shibboleth.authn.MFA.Transition" p:nextFlow="authn/AkamaiMfa" />
  </entry>
</util:map>
  • For an authentication that is provided by the third party in the first step and followed by the ​Akamai MFA​ second factor:
<util:map id="shibboleth.authn.MFA.TransitionMap">
  <entry key="">
    <bean parent="shibboleth.authn.MFA.Transition" p:nextFlow="authn/RemoteUser" />
  </entry>
  <entry key="authn/RemoteUser">
    <bean parent="shibboleth.authn.MFA.Transition" p:nextFlow="authn/AkamaiMfa" />
  </entry>
</util:map>

  1. If you specified multiple integrations in $IDP_HOME/conf/authn/akamaimfa.properties, uncomment the following lines in $IDP_HOME/flows/authn/AkamaiMfa/akamaimfa-authn-beans.xml:

    1. Uncomment the identifierMap bean and add more domain entries as needed: 
      <bean id="identifierMap" class="java.util.HashMap">
        <constructor-arg>
            <map>
                <entry key="%{akamaimfa.userIdentifier[0].identifier:#{null}}">
                    <bean class="net.shibboleth.idp.authn.pushzero.IdentifierConfig">
                        <property name="appId" value="%{akamaimfa.userIdentifier[0].appId:#{null}}" />
                        <property name="signingKey" value="%{akamaimfa.userIdentifier[0].signingKey:#{null}}" />
                        <property name="verifyingKey" value="%{akamaimfa.userIdentifier[0].verifyingKey:#{null}}" />
                    </bean>
                </entry>
                <entry key="%{akamaimfa.userIdentifier[1].identifier:#{null}}">
                    <bean class="net.shibboleth.idp.authn.pushzero.IdentifierConfig">
                        <property name="appId" value="%{akamaimfa.userIdentifier[1].appId:#{null}}" />
                        <property name="signingKey" value="%{akamaimfa.userIdentifier[1].signingKey:#{null}}" />
                        <property name="verifyingKey" value="%{akamaimfa.userIdentifier[1].verifyingKey:#{null}}" />
                    </bean>
                </entry>
            </map>
        </constructor-arg>
    </bean>
    2. Uncomment the isUserIdentifierApplicable and userIdentifier properties: 
      <property name="isUserIdentifierApplicable" value="%{akamaimfa.isUserIdentifierApplicable:#{null}}" />
<property name="userIdentifier" ref="identifierMap" />

  2. Edit $IDP_HOME/views/akamaimfa.vm to customize your setup.

  3. Rebuild the Shibboleth WAR file by running $IDP_HOME/bin/build.sh.

  4. Restart the Shibboleth IDP.

Installation of the ​Akamai MFA​ plugin for Shibboleth 4.0 or earlier

Follow these steps to install the Shibboleth plugin for ​Akamai MFA​. With this installation, you enable both sides of the integration to communicate with each other.

  1. Download the AkamaiMfaShibboleth.tgz package and extract its contents.

  2. Copy the below files from the cloned repositories to the following locations of your Shibboleth installation directory:

    • shibboleth-idp/conf/authn/akamaimfa.propertiesto $IDP_HOME/conf/authn/

    • shibboleth-idp/conf/authn/akamaimfa-authn-config.xmlto $IDP_HOME/conf/authn/

    • shibboleth-idp/system/flows/authn/akamaimfa-authn-beans.xmlto $IDP_HOME/system/flows/authn

    • shibboleth-idp/system/flows/authn/akamaimfa-authn-flow.xmlto $IDP_HOME/system/flows/authn

    • shibboleth-idp/views/akamaimfa.vmto $IDP_HOME/views/

    • js/akamaimfa.jsto $IDP_HOME/webapp/js/

      Where:

    • $IDP_HOME is a disk location of IDP home on the server machine

  3. Copy contents of shibboleth-idp/edit-webapp/WEB-INF/lib/to $IDP_HOME/edit-webapp/WEB-INF/lib/directory.

  4. Edit IdP properties files with ​Akamai MFA​ specific values.

    1. Edit $IDP_HOME/conf/authn/akamaimfa.propertiesfile with valid values for the below parameters:
      • idp.akamaimfa.apiHost
      • idp.akamaimfa.appId. This refers to Integration ID that you copied from ​Akamai​ integration page
      • idp.akamaimfa.signingKey. This refers to the Signing Key that you copied from the ​Akamai​ integration page
      • idp.akamaimfa.callbackUrl
    2. Edit $IDP_HOME/conf/idp.propertiesfile:
      • Add/conf/authn/akamaimfa.propertiesto idp.additionalPropertiesto let the ​Akamai MFA​ service access the above parameters

  5. Enable the ​Akamai MFA​ service with the following steps:

    1. Set idp.authn.flows= MFAin $IDP_HOME/conf/idp.propertiesfile

    2. Add the following tag to $IDP_HOME/conf/authn/general-authn.xml. file before `<bean id="authn/MFA":

      ...       
  <bean id="authn/AkamaiMfa" parent="shibboleth.AuthenticationFlow"
     p:forcedAuthenticationSupported="true"                 
     p:nonBrowserSupported="false">              
   <property name="supportedPrincipals">                 
    <list>                     
     <bean parent="shibboleth.SAML2AuthnContextClassRef" 
       c:classRef="http://akamai.com/mfa" />       
     <bean parent="shibboleth.SAML1AuthenticationMethod"
       c:method="http://akamai.com/mfa" />                 
    </list>             
   </property>         
  </bean> 
...

    3. Add one of the following tags to $IDP_HOME/conf/authn/mfa-authn-config.xmlfile.

      For an authentication that is password-based in the first step and followed by the ​Akamai MFA​ second factor, add the below snippet inside those tags: <util:map id="shibboleth.authn.MFA.TransitionMap"> and </util:map> :

      ...      
     <entry key="">            
        <bean parent="shibboleth.authn.MFA.Transition" p:nextFlow="authn/Password" /> 
     </entry>         
     <entry key="authn/Password"> 
        <bean parent="shibboleth.authn.MFA.Transition" p:nextFlow="authn/AkamaiMfa" />   
     </entry>   
          ...

      For an authentication that is provided by the third party in the first step and followed by the ​Akamai MFA​ second factor, add the below snippet inside those tags <util:map id="shibboleth.authn.MFA.TransitionMap"> and </util:map> :

      ...    
      <entry key="">  
          <bean parent="shibboleth.authn.MFA.Transition" p:nextFlow="authn/RemoteUser" />         	
      </entry>
      <entry key="authn/RemoteUser">  
       <bean parent="shibboleth.authn.MFA.Transition" p:nextFlow="authn/AkamaiMfa" />         
      </entry> 
...

    4. Add the below value before <entry key="authn/MFA"to edit $IDP_HOME/system/conf/webflow-config.xmlfile: 

    <entry key="authn/AkamaiMfa" value="../system/flows/authn/akamaimfa-authn-flow.xml" />

  6. Add the following snippet to $IDP_HOME/system/messages/messages.propertiesfile:

    ... 
idp.login.akamaimfaRequired = Authentication with Akamai MFA is required for the requested service. 
idp.login.akamaimfaNoScript = The Akamai MFA service requires JavaScript. 
idp.login.akamaimfaCancel = Cancel this Request 
...

  7. Edit $IDP_HOME/views/akamaimfa.vmfile to customize your setup.

  8. Rebuild the Shibboleth WAR file $IDP_HOME/bin/build.sh.

  9. Restart the Shibboleth IdP.

Updated 27 days ago