Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 21 Next »

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.

 A note against IdP-originated SSO

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 https://www.identityserver.com/articles/the-dangers-of-saml-idp-initiated-sso for a succinct argument against IdP-initiated SSO.

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.

 SP Parameters for an example IdP
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.

 IdP Metadata example
  1. Identity Provider Single Sign-On URL: (saml2.idp.single_sign_on_service.url)

    https://OURIDP.COM:IDPPORT/SSOPATH

  2. Identity Provider Issuer: (saml2.idp.entityid)

    http://OURIDP.COM:IDPPORT/SAMLIDP

  3. 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 (warning)

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

 silhouette.conf template
  # 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:

 Purpose 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

YES

"http://MYSP.MYCOMPANY.MYCOM:MYPORT/authenticate/SAML2"

saml2.sp.assertion_consumer_service.binding

saml2.sp.single_logout_service.url

saml2.sp.single_logout_service.binding

saml2.sp.nameidformat

saml2.sp.x509cert

saml2.sp.privatekey

saml2.idp.entityid

"https://OURIDP.IDPCOMPANY.IDPCOM:IDPPORT"

saml2.idp.single_sign_on_service.url

saml2.idp.single_sign_on_service.binding

saml2.idp.x509cert

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.

 application.conf template
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

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

  • No labels