5/18/2015

Syncplicity, How to use with Shibboleth


EMC Syncplicity is a a cloud based "Software as a Service" offering. The Syncplicity brand is owned by EMC Corporation. For companies that purchased substantial hosting services they create a custom branded EMC website for managing the cloud hosted accounts.

A cloud hosted account is a signed in user who has the ability to initiate and maintain a file storage session for the purpose of conducting file sharing services over the EMC Syncplicity cloud based file sharing system. Participants who maintain a cloud account are not individually licensed but receive web browser delivered software agents that enable their internet connected workstation or mobile device to use EMC cloud storage to share files.

Customers of EMC often already have an authentication system such as Active Directory, and often use ADFS or an OASIS style SAML2 compatible Single Sign On service in order to avoid proliferation of account management issues and to allow members of their domain to remember only one set of logon credentials.

Shibboleth is a commonly used SAML complaint SSO.

This is an example with Shibboleth 2.4.2 on RHEL6 connected to a Windows 2008r2 Domain.

Images: within this document are Expandable by "clicking" on them to enhance readability.

On the EMC provided Management page for the Customer service site

  •  NOTE:  When setting up SSO  "the Management page"  may log you out automatically after 30 minutes (before you are finished) . You can log back in regardless of whether SSO is enabled by going to the my.syncplicity.com website and "clicking" the triangle for  Sign-in Help   it will take you back to the Admin page for your subdomain account.

After signing into the EMC Management site you begin by choosing from the

Menu bar > Admin > Settings

Manage Settings
>Account Configuration
>>Custom Domain and single sign-on.




STEP 1

> Configuration Authentication Settings
>> Domain Settings (should already be filled out for you)

> Single Sign-On (SSO)
>> Single Sign-On Status*

"select" the radio button [Enabled] to un-grey the fields that follow


STEP 2

upload a PEM format X.509 copy of your Shibboleth Idp "internal" signing certificate:

[NOTE: This is the Idp "internal" cert used for signing SAML assertions. It is NOT the SSO Website certificate a users browser receives when they are directed to a logon page]

For example:

The SAML signing cert for Shibboleth is commonly placed here:

/opt/shibboleth-idp/credentials/idp.crt



 Master Tip! 

be sure to take a look at the [Current Certificate: ] information after it uploads

it is common for an Idp cert to reveal very little information

"too much" information could signal the  wrong  cert was uploaded


"the right" amount of information signals the  right  cert was uploaded 


STEP 3

complete the rest of the fields that refer to the Shibboleth server hosted at your site



Provide the Identity provider (Entity Id) for the Shibboleth Idp website:  < on your server > 

Provide the Customer facing "Sign-in page" (SSO) url:  < on your server > 

Provide the Customer facing "Logout page" (SSO) url:  < on your server > 

The press  [ Save Changes ]  to save the settings.


note: these are "paths" to web services on your shibboleth server, they have to be setup on your shibboleth server to receive requests and provide answers; they can be mapped to different paths, you have to be sure to use the correct paths; these are provided as common examples


On the Shibboleth server


STEP 1

The EMC website needs to be added as a Service Provider to the relying-party file.

The EMC website will be "relying" on your Shibboleth server to provide "authentication".

For example:

The shibboleth relying-party file is commonly found here:

/opt/shibboleth-idp/conf/relying-party.xml



The file is in xml format and has a series of "chunks" or "sections" of information


Syncplicity needs a new section like this
 rp:RelyingParty

Where id = "Service provider (SP id) for the EMC hosted website /sp"
Where provider = "Identity provider (Entity ID) for your shibboleth svr"
to save time and typing errors you can copy an existing section and modify it

Syncplicity needs to be added to this section
metadata:MetadataProvider

the Metadata that goes into the file
/opt/shibboleth-idp/metadata/emcshib.xml
has to come from EMC and is specific to your hosted service
here is what it looks like

the Metadata is a "contract" for how the Service Provider will communicate
it includes the SP id, the SAML protocol type, the SP x509 signing cert, what it expects to see used in the Subject line for communications (the "NameID") and how to contact the Service Provider when the Shibboleth server is done fullfilling the User login request
you can obtain it in one of three ways; 

1. https://custdomain.syncplicity.com/Auth/ServiceProviderMetadata.aspx
wget https://customain.syncplicity.com/Auth/ServiceProviderMetadata.aspx -O emcshib.xml
curl https://custdomain.syncplicity.com/Auth/ServiceProviderMetadata.aspx > emcshib.xml
 NOTE:  this method currently retrieves metadata with a known problem

2. https://syncplicity.zendesk.com
sign up for a Syncplicity Support account and "open" a Support Ticket
 NOTE:  support will review the ticket and may take up to 1 day to respond 

3. write it yourself
obtaining the Service Provider x509 cert is the only really hard part
you can fetch that from the URL for your hosted site in method # 1

STEP 2

The attributes to be returned to the service provider after a successful login need to be defined.

The required attributes need to be added to 

/opt/shibboleth-idp/conf/attributes-resolver.xml 


Syncplicity needs a new section like this

 resolver:AttributeDefinition

 

a particular attribute is not required, but at least one must be capable of being turned into the "Name ID" for the conversation; and it must be tagged as being formatted as a

nameid-format:emailAddress 


For example

we invent an attribute "EmcID" and fill it with the users mail address from an LDAP query to Active Directory for the authenticated user and tag it as being formatted as a  

nameid-format:emailAddress  

and SAML encode it with the SAML2StringNameID routine


the result will be when it comes time to pare down the attributes to be sent back to the EMC Syncplicity service provider, this attribute will be available


STEP 3

The attributes to be released need to be defined in the attribute-filter policy file.

The attributes to be released need to be added to 

/opt/shibboleth-idp/conf/attributes-filter.xml 


Syncplicity needs a new section like this

 afp:AttributeFilterPolicy


an AttributeFilterPolicy applies to a particular Service Provider ID and declares what attributes are Permitted or Denied release, usually you will have more Deny rules than Permit rules


in a SAML2 based server its also important to filter out the "Transient ID" explicitly since it is by default Permitted and often unintentionally takes the place of the NameID

after all rules are applied to pare down the available attributes for a user, one is selected for the NameID and based on the Metadata from the Service Provider it uses an attribute that is in the format

nameid-format:emailAddress  

Syncplicity will use this attribute to find the User Account on the hosted Service Provider site and log them in


STEP 4


Services need to be stopped and started to pick up the changes.

# service tomcat stop
# service tomcat start

And a Shibboleth / Active Directory user should attempt to login to the EMC provided Service site

It will take them to their familar Shibboleth SSO logon page for authentication.

After authentication it will return them to the same EMC Service Site and if their

 NameID = nameid-format:emailAddress 

matches a User Account created in the EMC management page for this site.

They will be allowed to initiate a Syncplicity file sharing session.

To be completely clear

Syncplicity "uses" an Email address as the UID or Unique Identifier for a Syncplicity user account in their system. Shibboleth must return a NameID in an email address format that Syncplicity can use to "find" a Syncplicity user account in the EMC system. If it fails to find a match the user may indeed succeed in logging in with their SSO credentials but Syncplicity will present an error screen indicating it could not match up their login with a Syncplicity user account.

It is also not enough to return or "assert" an attribute for a successfully logged in user, it must be mapped or used as the NameID for the SAML conversation. Syncplicity does not scan the attributes returned for "any" email address, it only looks at the NameID of the SAML conversation.

This is "why" it is so critical to make sure a Transient ID doesn't get accidentally mapped into the NameID. It is in the wrong format and will not in general be sourced from the mail attribute for a user.

You can tell from the log messages in the idp-process.log when detail is turned up, which released attribute is being "used" for the NameID. This is a terrific troubleshooting step.

Its even easier if you use a SAML tracer plugin on Firefox to "watch" what is used as the NameID in the conversation between the browser and Syncplicity when it returns from a successful SSO sign in.

Which released attribute will be picked for the NameID can seem a bit random in nature depending on the attributes available after all the attribute filters for that service provider have been applied.


 TroubleShooting Tips! 


 TIP #1 

The logging for Idp, OpenSAML, LDAP and Protocol messages can be increased in this file

/opt/shibboleth-idp/conf/logging.xml

After restart the tomcat Shibboleth process will record additional detail in

/opt/shibboleth-idp/logs/idp-access.log
/opt/shibboleth-idp/logs/idp-audit.log
/opt/shibboleth-idp/logs/idp-process.log
  
the ipd-process.log file will contain the most useful information.

these log files typically roll over at midnight local time.

Be sure to reduce the logging detail after troubleshooting.


 TIP #2  

The Firefox web browser has a SAML transaction decoder and monitoring tool [ Add-on ]

 NOTE:  works with Firefox version 29.0 and later "only"  


After it is installed

> Tools
>> SAML tracer

will open a separate box and track all of the traffic within open browser windows

traffic identitied as encrypted and SAML encoded will be decrypted and decoded into human readable content (can you 'Spot' the <saml2:NameID > line?)




 Be Careful  when sharing screenshots of decrypted SAML sessions as there is often "sensitive" user information exchanged within the SAML transactions 


 TIP #3  

Once SSO is enabled, only Users with accounts already set up in Syncplicity will be able to log into their Syncplicity accounts.

To be clear

If "End-users" merely visit the hosted portal site at <custom-domain>.syncplicity.com and try to login with their SSO credentials. They may indeed succeed in authenticating, but upon return from their SSO login page Syncplicity "will not" proceed with the "Self-signup" process. They will be denied access.

   Setting up "End-user self-signup" is a completely separate Administrative task.    

Once it is configured and enabled End-users will need a specially crafted "invitation URL" created for the Syncplicity hosted domain in order to begin the self-signup process.

The "invitation URL" is unique to the hosted site, but not to the End-user, so once it is created the same URL can be shared with everyone who is entitled within an organization to participate.