7.1 Integrating Advanced Authentication with SAML 2.0

To integrate Advanced Authentication with the third-party solutions using SAML 2.0, perform the following steps

  1. Click Events > Add.

  2. Specify a name for the new event.

  3. Change the Event type to SAML2.

  4. Select the required chains for the event.

  5. Copy and paste your Service Provider's SAML 2.0 metadata to SP SAML 2.0 metadata.

    OR

    Click Browse and select a Service Provider's SAML 2.0 metadata XML file to upload it.

  6. Click Policies > Web Authentication.

  7. (Conditional) Specify the Identity Provider’s URL in Identity provider URL.

    NOTE:To use multiple Advanced Authentication servers with SAML 2.0, you must do the following:

    1. Configure an external .

    2. Specify the address in Identity provider URL instead of specifying an address of a single Advanced Authentication server.

  8. Click Download IdP SAML 2.0 Metadata to open a metadata.The metadata opens in a new browser page.

  9. Save the metadata (XML text) from the browser.

  10. (Conditional) Use the downloaded metadata file in your Service Provider.

  11. (Conditional) Use the Identity Provider certificate in your Service Provider.

    -----BEGIN CERTIFICATE-----
MIIDkzCCAnugAwIBAgIESsmdMzANBgkqhkiG9w0BAQsFADB6MRAwDgYDVQQGEwdVbmtub3duMRAw
DgYDVQQIEwdVbmtub3duMRAwDgYDVQQHEwdVbmtub3duMREwDwYDVQQKEwhBdXRoYXNhczESMBAG
A1UECxMJQXV0aGFzYXNhMRswGQYDVQQDExJvc3AuYXV0aGFzYXMubG9jYWwwHhcNMTYwNTI2MDUz
NjI0WhcNMjYwNDA0MDUzNjI0WjB6MRAwDgYDVQQGEwdVbmtub3duMRAwDgYDVQQIEwdVbmtub3du
MRAwDgYDVQQHEwdVbmtub3duMREwDwYDVQQKEwhBdXRoYXNhczESMBAGA1UECxMJQXV0aGFzYXNh
MRswGQYDVQQDExJvc3AuYXV0aGFzYXMubG9jYWwwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEK
AoIBAQCw3YLz03qhSZPXjBc/Ws+cZ2/E5oogqKeJ3p4RR6USOoarjnmvQPq+maRfvexriwQjRDgS
OFRb58cert/misqzsHBVmQDnfMwicFVzuuKjDEbWFp9vL1gRkDzIlpCyl3eNmBWuWXM49Z6mm8XS
fIwlAoydNp5DK0o0Yrk6FNOi0nOrnI5kHGVD0bd5SpDtvXSF1WLfc5YT9UBUpfZneKsVPWSkbeBX
F84hYJWBtdzcTEyjdso9Ra7UtxLIUW0UH3LWTgn9zS97nLkmhetmD1I3mEAeAE9SAmqTRyH1FNXZ
ZOfi/BJF4+sz86f6pBbwYM2KTvXaABgzSpZpJ1pQrZKPAgMBAAGjITAfMB0GA1UdDgQWBBTL8PbA
+e6YkBIk4yELTZ+AbfdA6DANBgkqhkiG9w0BAQsFAAOCAQEAm87lNyAO8CtN5jlLe3CupLAAbUWR
NY6av7LpPail1JRIw+uvddMyOz1vOS1IwpDDNtcPtxGXsaZI1CKgNPBpLvSxePVUXNfFgUCtu+bT
cuUtiQbkiDWwFLmAS6KeA+EBFOeqBiudEfkAZZT87DF9gKvM6VWdzJ7BvWi2YPbH/FRM82fLoyAd
RbphF215we3rvsfeWbwXw70UGNyBUTb3zUcAmB3sHbcZiXJZj3pJYgDaN9Ss60sz/yG1ZLEYluvL
R1T2PPEfEcA1Eij0R1A31Z5hJ3zDlXoCeNYLoMg4522QYekTwvQeWkeYejBXEcxdL7VP6F91zmfZ
bm1A4PY5jw==
-----END CERTIFICATE-----

  12. Change used hash to SHA-1 in your Service Provider, if the option is presented.

  13. Set the Send E-Mail as NameID (suitable for G-Suite) option to ON for integrating with the G-suite.

  14. Set the Send SAMAccount as NameID option to ON to send SAMAccountName in the NameID attribute as a SAML response from the Advanced Authentication server.

    WARNING:You can set Send SAMAccount as NameID to ON only when the Send E-Mail as NameID (suitable for G-Suite) option is turned OFF.

  15. Set Bypass user lockout in repository to ON, if you want to allow users who are locked on repository to authenticate on the Advanced Authentication. By default, Bypass user lockout in repository is set to OFF and users who are locked on repository are not allowed to authenticate.

The following are the examples of integration with SAML 2.0.

7.1.1 Requesting Advanced Authentication Methods and Chains Through a SAML AuthnRequest

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 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