To integrate Advanced Authentication with the third-party solutions using SAML 2.0, perform the following steps
Create a SAML 2.0 event. For more information on how to create a event, see Creating a SAML 2.0 event.
Click Policies > Web Authentication.
(Conditional) Specify the Identity Provider’s URL in Identity provider URL. For more information, see Configuring the identity provider.
NOTE:To use multiple Advanced Authentication servers with SAML 2.0, you must do the following:
Configure an external load balancer.
Specify the address in Identity provider URL instead of specifying an address of a single Advanced Authentication server.
(Conditional) Click IdP SAML 2.0 Metadata to download the SAML 2.0 metadata. You can download the SAML 2.0 metadata file only when the Identity Provider's URL is configured. The downloaded SAML 2.0 metadata file is used to configure the Service Provider.
Click Save.
Click Server Options > Signing Certificate and save the certificate content in a notepad file for further use.
NOTE:Use the Identity Provider Signing certificate in your Service Provider.
NOTE:The logout URL must follow the below format:
https://<AAServer>/osp/a/TOP/auth/app/logout
where TOP is the name of the tenant.
However, it is possible to perform the logout from both Identity Provider and Service Provider using the following URL:
https://<AAServer>/osp/a/TOP/auth/app/logout?target=https://<Service Provider>/app/logout
For example: https://<AAServer>/osp/a/TOP/auth/app/logout?target=https://<NAMServer>/nidp/app/logout
The following are the examples of integration with SAML 2.0.
SAML 2.0 provides a mechanism to request an authentication class reference. For more information, see the SAML 2.0 Core specification in section 3.3.2.2.1.
The Service Provider sends the following sample code in the <AuthnRequest>:
<samlp:RequestedAuthnContext> <saml:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:MobileOneFactorContract</saml:AuthnContextClassRef> </samlp:RequestedAuthnContext>
SAML 2.0 defines a bunch of URNs that corresponds to authentication classes. For more information, see SAML 2.0 Authentication Context.
Some of the authentication class types of Advanced Authentication match the SAML 2.0 references. The Advanced Authentication auth class types are defined in an enum named AuthClassType.
In this XML example, the SAML class reference URN maps to the Advanced Authentication’s AuthClassType.MOBILE_ONE_FACTOR_CONTRACT. The Advanced Authentication value is mapped to NaafAuthMethod.SMARTPHONE (or NaafAuthMethod.SWISSCOM).The code in NaafEventContractExecutable.filterChains selects from the available chains any chain that contains one of its methods (in this example) SMARTPHONE or SWISSCOM. (The map from Advanced Authentication methods to OSP auth class type is NaafContractExecutable.METHOD_TO_TYPE_MAP.)
In this example, after the user is identified, if there is a chain available with the Smartphone or Swisscom methods, then the authentication proceeds. If not, the authentication fails and Advanced Authentication returns a no requested authentication context status to the Service Provider.
An optional Comparison attribute can be set on the <RequestedAuthnContext>. This attribute is defined in the SAML 2.0 Core specification in section 3.3.2.2.1.
In addition to requesting the Advanced Authentication methods using the SAML 2.0-defined URNs, Advanced Authentication also has a special contract parameters class reference URN. The URN is: urn:uuid:519a6c73-f092-43d3-ab11-8d789ebc2f79.
The contract parameters are added through the URN q-component. The URN syntax is defined at RFC 8141.
The <NaafEvent> contract executable contains attributes named allowClientChainSelection and allowClientEventSelection. These attributes allow the authentication chain and the authentication event to be selected through a contract parameter from the client, which in this example, is the SAML Service Provider. In the Advanced Authentication authcfg.xml, the default value of allowClientEventSelection is false and allowClientChainSelection is true.
For example, ISM is an event name with the following chains: LDAP+Smartphone, LDAP+SMS_OTP, LDAP+TOTP, LDAP+SecQuest, LDAP+U2F, and LDAP+Voice.
If the <NaafEvent> contract executable is configured with the ISM event, then the following code will request the LDAP+SMS_OTP chain.
<samlp:RequestedAuthnContext> <saml:AuthnContextClassRef>urn:uuid:519a6c73-f092-43d3-ab11-8d789ebc2f79?=internal.osp.oidp.aa.chain-name=LDAP%2BSMS_OTP</saml:AuthnContextClassRef> </samlp:RequestedAuthnContext>
The plus sign '+' is encoded as '%2B'. Advanced Authentication considers that the q-component, which starts with ?=, is in the x-www-form-urlencoded format and '+' is a reserved character for this syntax.
The two contract parameters that are defined in the Advanced Authentication class CFGNaafEvent are:
internal.osp.oidp.aa.chain-name
internal.osp.oidp.aa.event-name