Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Table of Contents
minLevel2
maxLevel2
outlinetrue

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.

...

  • 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/confs/web-gateway-impl/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

Expand
titlesilhouette.conf template
Code Block
languageyaml
  # 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 = "sha1http://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"

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.

...

titleapplication.conf template

...

languagejava

...

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

Expand
titlePurpose of each Syndeia Silhouette SAML setting

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.

Expand
titleapplication.conf template
Code Block
languagejava
play.filters.enabled += play.filters.hosts.AllowedHostsFilter
play.filters.hosts {
  # You can use the "." pattern to match all hosts (not recommended in production).
  # Note that the filter also strips the dot character from the end of the host, so the example.com pattern will match example.com.
  # Uncomment to allow requests to intercax.com, its subdomains, and localhost:9000.
  # allowed = [".intercax.com", "localhost:9000"]
  allowed = ["."]
}

# Security Filter Configuration - Content Security Policy
play.filters.headers {
  contentSecurityPolicy = "default-src 'self';"
  contentSecurityPolicy = ${play.filters.headers.contentSecurityPolicy}" connect-src 'self' https://OURIDP.COM:IDPPORT;"
  contentSecurityPolicy = ${play.filters.headers.contentSecurityPolicy}" img-src 'self';"
  contentSecurityPolicy = ${play.filters.headers.contentSecurityPolicy}" style-src 'self' 'unsafe-inline';"
  contentSecurityPolicy = ${play.filters.headers.contentSecurityPolicy}" font-src 'self' 'unsafe-inline';"
  contentSecurityPolicy = ${play.filters.headers.contentSecurityPolicy}" script-src 'self' 'unsafe-inline' 'unsafe-eval';"
}

# the /authenticate/SAML2 route needs this to be able to pass crucial Headers back
# to the frontend
play.filters.headers.allowActionSpecificHeaders = true

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

...

 pass crucial Headers back
# to the frontend
play.filters.headers.allowActionSpecificHeaders = true

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.