SAML2 Configuration

Syndeia supports delegated Authentication to an organization’s choice of Identity Providers – for those Identity Providers which offer support for the OASIS standard “Security Assertion Markup Language 2.0” (SAML 2.0).

Configuration of Syndeia for SAML2 Authentication requires that Syndeia Cloud’s silhouette.conf and application.conf be edited to inform the Syndeia web-gateway service of the location and the settings of the peer SAML2 IdP.

Configuration of the corporate network for Syndeia SAML2 Authentication further requires that the chosen IdP be configured to recognize Syndeia Cloud as a legitimate SAML2 Service Provider.

For security reasons and to follow industry best cybersecurity practices, Syndeia Cloud only offers “SP-originated, delegated-to-IdP” authentication. Syndeia Cloud does not support “IdP-initiated, SSO-login”.

See The Dangers of SAML IdP-Initiated SSO for a succinct argument against IdP-initiated SSO.

1 Preparation Tasks
2 Configure the IdP
3 Configure your Organization
4 Configure silhouette.conf
5 Configure application.conf
6 Operation

Preparation Tasks

Deploy Syndeia Cloud according to Intercax Documentation.
Read as much of SAML Explained in Plain English as you need to be fluent in SAML2 terms and administration.
Assure that the browsers on the user workstations which are going to interact with Syndeia Web Dashboard and with the chosen IdP can connect to both the SP and the IdP and that there are no SSL certificate denials.
Assure that there are no traffic shapers on the corporate network that alter HTTP Request and HTTP Response Headers - especially those headers involved in CORS and CSP protocols.
Assure that there are no network routers or proxies on the corporate network that alter HTTP URLs or that alter HTTP Location Headers.
Obtain the Fully-qualified Network Domain (FQDN) scheme, host, and port of the Syndeia Cloud SP - as it will be recognized by the IdP.
Obtain the FQDN scheme, host, and port of the chosen IdP.
Study the IdP guides on its choices for the many options in compression and signing of content exchanged in SAMLRequest and SAMLResponse HTTP traffic.

For the purposes of this guide only, the Syndeia Cloud server is referred to as MYSP.COM and the chosen SAML2 IdP is referred to as OURIDP.COM

Configure the IdP

Browse to and authenticate into your organization’s choice of IdP’s administration web site
Enter the “Application” management portion of this administration web site
Create a new SSO SAML2 IdP service for the IdP’s users
Configure this new or additional IdP to trust your Syndeia Cloud SP
The following example is for configuration of an Okta Application as a SAML2 IdP for a Syndeia Cloud SP. Actual values will differ based on your Syndeia Cloud location and on your chosen IdP service.

Single Sign On URL
http://MYSP.COM:SPPORT/authenticate/SAML2
Recipient URL
http://MYSP.COM:SPPORT/authenticate/SAML2
Destination URL
http://MYSP.COM:SPPORT/authenticate/SAML2
Audience Restriction
http://MYSP.COM:SPPORT
Default Relay State
Name ID Format
EmailAddress
Response
Signed
Assertion Signature
Signed
Signature Algorithm
RSA_SHA256
Digest Algorithm
SHA256
Assertion Encryption
Unencrypted
SAML Single Logout
Disabled
authnContextClassRef
PasswordProtectedTransport
Honor Force Authentication
Yes
Assertion
Inline Hook
None (disabled)
SAML Issuer ID
http://OURIDP.COM/${org.externalKey}

ATTRIBUTE STATEMENTS

Name  Name Format  Value
uid  Basic  user.login
first_name. Basic  user.firstName
last_name  Basic  user.lastName
fullname  Basic  user.firstName + " " + user.lastName + " (" + user.login + ")"
email Basic  user.email

After you have informed your IdP about your Syndeia Cloud SP, it will offer you “SAML Metadata” for the SP’s configuration. The following shows example metadata from an Okta Application acting as IdP for a Syndeia Cloud SP. The corresponding silhouette.conf property is shown for each IdP Metadata property to help clarify where to copy the values.

Identity Provider Single Sign-On URL: (saml2.idp.single_sign_on_service.url)
https://OURIDP.COM:IDPPORT/SSOPATH
Identity Provider Issuer: (saml2.idp.entityid)
http://OURIDP.COM:IDPPORT/SAMLIDP
X.509 Certificate: (saml2.idp.x509cert)
-----BEGIN CERTIFICATE----- MIIDyjCCArKgAwIBAgIGAX5n+/A8MA0GCSqGSIb3DQEBBQUAMIGlMQswCQYDVQQGEwJVUzETMBEG A1UECAwKQ2FsaWZvcm5pYTEWMBQGA1UEBwwNU2FuIEZyYW5jaXNjbzENMAsGA1UECgwET2t0YTEU MBIGA1UECwwLU1NPUHJvdmlkZXIxJjAkBgNVBAMMHWludGVyY2F4dGVzdGludGVyY2F4d29ya2Zv cmNlMRwwGgYJKoZIhvcNAQkBFg1pbmZvQG9rdGEuY29tMB4XDTIyMDExNzEyMjAxMVoXDTMyMDEx SOME LONG SSL CERT CONTENT 2gfYlFQdLt/EH5KeonaR7dysO+cp01rzpVSv3ZT0Q4mWW5P8vEsO95NsFCVOxD6RPM+8jaAtMPWX uR4n76w4yIF2BF5kHEfufzdMr+eNTb6eBnQq9YGYoAwMFPrSDzflZcUv4FLmXC6T+BqAI9wdyYrF jJ8DDG29Vbq2MW9oztspAcADr8e4ORIm4I3tw1/jkH4y2ZvRrtWK05+aWhjEju8b/R8kFV6mH9Ks 2TcYbAY= -----END CERTIFICATE-----

Note that your IdP must provide SAML Attributes for the authenticated user. The names of those Attributes can differ (you will specify the actual names in the silhouette.conf files – but a value for each Attribute with the right meaning must be provided. For example, your IdP must supply some form of unique email address for each user it authenticates. This email address might be called anything – “email”, “address”, “loginString”, etc. It simply must be named and be given a value.
Note that your IdP might use different domain names and ports for itself and for this particular SAML2 IdP service. In all cases, use the values that your IdP provides. All values must match precisely.

Configure your Organization

With SAML2, all management of user identities, access policies, choice of access to applications, choice of permissible primary and secondary authentication factors, use of passwords or PIV/CAC cards are all the responsibility and choice of the organization.

Assure the IdP has access policies in place and know those
Assure the IdP has a directory of user identities
Know which users or groups should be permitted access to the Syndeia Service Provider
Selectively assign access to the Syndeia Cloud application to the right users

Users in the organization will not be able to access Syndeia Cloud through SAML2 SSO until the organization grants them access through the administration in the IdP.

Configure `silhouette.conf`

ssh log into the Syndeia Cloud server with a user that can perform “passwordless sudo” operations. Root access is not necessary, if sudo access has been established.
cd to /opt/icx/syndeia-cloud-current/web-gateway-3.6/conf
copy all of the following into silhouette.conf, adding or replacing any existing saml2. settings.
Replace all EXAMPLE values – like MYSP.COM:SPPORT– with the values for your organization.
When specifying encryption and signing algorithms, use the long URI formats
- See https://www.w3.org/TR/xmlsec-algorithms/#signature-method-uris

  # SAML2 Provider
  # These settings are intentionally similar to what OneLogin needs for SAML2
  # Service Providers and Identity Providers

    # Compression settings. Note that these are determined by OASIS Standard for SAML2
    # false => Base64 encoded, true => Deflated Base64 encoded (which is compressed)
	# saml2.compress.request = true
	# saml2.compress.response = true

    saml2.security.authnrequest_signed = true
    saml2.security.want_messages_signed = true
    saml2.security.want_assertions_signed = true
    saml2.security.want_xml_validation = true
    saml2.security.signature_algorithm = "http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"
    saml2.security.requested_authncontext = "exact"

    # CAC/PIV authentications might need something like this, which is IdP-specific
    # saml2.security.requested_authncontext = "http://idmanagement.gov/ns/assurance/aal/3?hspd12=true"

    #  Identifier of the SP entity  (must be a URI)
    saml2.sp.entityid = "http://MYSP.COM:SPPORT"

    # Specifies info about where and how the <AuthnResponse> message MUST be
    #  returned to the requester, in this case our SP.
    # URL Location where the <Response> from the IdP will be returned
    saml2.sp.assertion_consumer_service.url = "http://MYSP.com:SPPORT/authenticate/SAML2"

    # SAML protocol binding to be used when returning the <Response>
    # message.  Onelogin Toolkit supports for this endpoint the
    # HTTP-POST binding only
    saml2.sp.assertion_consumer_service.binding = "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"

    # Specifies info about where and how the <Logout Response> message MUST be
    # returned to the requester, in this case our SP.
    saml2.sp.single_logout_service.url = "http://MYSP.com:SPPORT/authenticate/SAML2"

    # SAML protocol binding to be used when returning the <LogoutResponse> or sending the <LogoutRequest>
    # message.  Onelogin Toolkit supports for this endpoint the
    # HTTP-Redirect binding only
    saml2.sp.single_logout_service.binding = "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"

    # Specifies constraints on the name identifier to be used to
    # represent the requested subject.
    # Take a look on lib/Saml2/Constants.php to see the NameIdFormat supported
    saml2.sp.nameidformat = "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress"

    # Usually x509cert and privateKey of the SP are provided by files placed at
    # the certs folder. But we can also provide them with the following parameters
    saml2.sp.x509cert = "-----BEGIN CERTIFICATE-----BIGLONGSPPUBLICCERTSTRING-----END CERTIFICATE-----"

    # Requires Format PKCS#8   BEGIN PRIVATE KEY
    # If you have     PKCS#1   BEGIN RSA PRIVATE KEY  convert it by   openssl pkcs8 -topk8 -inform pem -nocrypt -in sp.rsa_key -outform pem -out sp.pem
    saml2.sp.privatekey = "-----BEGIN PRIVATE KEY-----BIGLONGSPPRIVATECERTSTRING-----END PRIVATE KEY-----"

    # Identifier of the IdP entity  (must be a URI)
    saml2.idp.entityid = "http://OURIDP.COM:IDPPORT/SAMLIDP"

    # SSO endpoint info of the IdP. (Authentication Request protocol)
    # URL Target of the IdP where the SP will send the Authentication Request Message
    saml2.idp.single_sign_on_service.url = "https://OURIDP.COM:IDPPORT/SSOPATH"

    saml2.idp.single_sign_on_service.binding = "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"

    # Instead of using the whole x509cert you can use a fingerprint in order to
    # validate a SAMLResponse (but you still need the x509cert to validate LogoutRequest and LogoutResponse using the HTTP-Redirect binding).
    # But take in mind that the fingerprint, is a hash, so at the end is open to a collision attack that can end on a signature validation bypass,
    # that why we don't recommend it use for production environments.
    # (openssl x509 -noout -fingerprint -in "idp_crt" to generate it,
    # or add for example the -sha256 , -sha384 or -sha512 parameter)

    # If a fingerprint is provided, then the certFingerprintAlgorithm is required in order to
    # let the toolkit know which Algorithm was used. Possible values: sha1, sha256, sha384 or sha512
    # 'sha1' is the default value.
    #saml2.idp.certfingerprint = "1234"
    #saml2.idp_certfingerprint_algorithm = "sha1"

    saml2.idp.x509cert = "-----BEGIN CERTIFICATE-----BIGLONGIDPPUBLICCERTSTRING-----END CERTIFICATE-----"

    # These are the property keys used to retrieve Social Identity information from the SAML2 Response which an IdP
    # sends back to an SP. The names of the keys are standardized but are configurable here to support internationalization
    # and quirks by IdP vendors like Microsoft
    saml2.social.attribute.key.uid = "uid"
    saml2.social.attribute.key.firstname = "first_name"
    saml2.social.attribute.key.lastname = "last_name"
    saml2.social.attribute.key.fullname = "fullname"
    saml2.social.attribute.key.email = "email"

Curious about the purpose of each and every setting? Expand this:

Setting	Purpose	Mandatory?	Typical

Setting	Purpose	Mandatory?	Typical
`saml2.compress.request`	Should the SP compress the SAML2Request XML?	NO - defaults to true	true
`saml2.compress.response`	If the SP sends a SAMLResponse, should it compress the XML?	NO - defaults to true	true
`saml2.security.authnrequest_signed`	Will the SP digitally sign its AuthnRequest inside the SAMLRequest?	YES	true
`saml2.security.want_messages_signed`	Does the SP want the IdP to digitally sign its SAML messages?	YES	true
`saml2.security.want_assertions_signed`	Does the SP want the IdP to digitally sign its SAML assertions?	YES	false
`saml2.security.want_xml_validation`	Should the SP validate all outbound and incoming SAML XML?	YES	true
`saml2.security.signature_algorithm`	The W3 URI for an XML Signature Algorithm	YES	"http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"
`saml2.security.requested_authncontext`	The requested AuthnContext the SP wants from the IdP	YES	“exact”
`saml2.sp.entityid`	The URI of the Syndeia service as SP	YES	"http://MYSP.MYCOMPANY.MYCOM:MYPORT"
`saml2.sp.assertion_consumer_service.url`	The SAML2 authentication endpoint at the Syndeia SP for SSO login	YES	"http://MYSP.MYCOMPANY.MYCOM:MYPORT/authenticate/SAML2"
`saml2.sp.assertion_consumer_service.binding`	The selection of the SAML2 protocol that the SP will use to direct the User-Agent to the IdP	YES - HTTP-POST only	"urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
`saml2.sp.single_logout_service.url`	The SAML2 authentication endpoint at the Syndeia SP for SLO logoff	YES - but unused	"http://MYSP.MYCOMPANY.MYCOM:MYPORT/authenticate/SAML2"
`saml2.sp.single_logout_service.binding`	The selection of the SAML2 protocol that the IdP would use to direct the User-Agent to the SP during SLO logoff	YES - HTTP-Redirect only	“urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect”
`saml2.sp.nameidformat`	The the name identifier to be used to represent the requested subject	YES	"urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress"
`saml2.sp.x509cert`	The PEM-format of the Public X.509 certificate of the SP	YES	“-----BEGIN CERTIFICATE…”
`saml2.sp.privatekey`	The PKCS#8-format of the Private Key for the SP	YES	"-----BEGIN PRIVATE KEY…”
`saml2.idp.entityid`	The URI of the SAML2 identity provider service as IdP	YES	"https://OURIDP.IDPCOMPANY.IDPCOM:IDPPORT"
`saml2.idp.single_sign_on_service.url`	The SAML2 authentication endpoint at the Syndeia SP for SSO login	YES	“https://OURIDP.IDPCOMPANY.IDPCOM/SSOPATH”
`saml2.idp.single_sign_on_service.binding`	The selection of the SAML2 protocol that the SP will use to direct the User-Agent to the IdP	YES - HTTP-Redirect only	“urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect”
`saml2.idp.x509cert`	The PEM-format of the Public X.509 certificate of the IDP	YES	“-----BEGIN CERTIFICATE…”
`saml2.social.attribute.key.uid`	In the SAML Attributes provided by the IdP, what is the key name for the Attribute that holds the user identifier?	YES	“uid”
`saml2.social.attribute.key.firstname`	In the SAML Attributes provided by the IdP, what is the key name for the Attribute that holds the user’s first name?	YES	“first_name”
`saml2.social.attribute.key.lastname`	In the SAML Attributes provided by the IdP, what is the key name for the Attribute that holds the user’s last name?	YES	“last_name”
`saml2.social.attribute.key.fullname`	In the SAML Attributes provided by the IdP, what is the key name for the Attribute that holds the user’s full or display name?	YES	“fullname”
`saml2.social.attribute.key.email`	In the SAML Attributes provided by the IdP, what is the key name for the Attribute that holds the user’s email address?	YES	“email”

Configure `application.conf`

ssh log into the Syndeia Cloud server with a user that can perform “passwordless sudo” operations. Root access is not necessary, if sudo access has been established.
copy all of the following into application.conf, adding or altering the following Akka Play HTTP settings.
Replace all EXAMPLE values – like OURIDP.COM:IDPPORT– with the values for your organization.

Operation

To log into Syndeia’s Web Dashboard via SP-originated SSO using your choice of SAML2-supporting IdP:

complete all configuration tasks
restart the Syndeia Web Gateway service
open a new browser
flush the browser caches
visit the Syndeia Cloud LoginForm at http:MYSP.COM:SPPORT
click the LOGIN WITH SSO link and complete the IdP’s authentication challenges.

Syndeia API Access

To allow a user that has authenticated into the Syndeia Web Dashboard with a web-flow SSO session to be able to execute programs or scripts which make API calls to Syndeia’s REST endpoints, the SSO user will need a Basic Authentication password (or pass phrase) – and one is not automatically stored by Syndeia during the SSO login.

Therefore, use the Syndeia API /resetPassword endpoint to grant the user a password which can be used with their email address to make all other Syndeia API calls.