Edit

SAML integration

SAML 2.0

SAML (Security Assertion Markup Language) is an XML-based, open-standard data format for exchanging authentication and authorization data between parties, in particular, between an identity provider (IdP) and a service provider (SP)

The SAML specification defines three roles: the principal (typically a user), the Identity provider (IdP), and the service provider (SP). In the use case addressed by SAML, the principal requests a service from the service provider. The service provider requests and obtains an identity assertion from the identity provider. On the basis of this assertion, the service provider can make an access control decision – in other words it can decide whether to perform some service for the connected principal.

Before delivering the identity assertion to the SP, the IdP may request some information from the principal – such as a user name and password – in order to authenticate the principal. SAML specifies the assertions between the three parties: in particular, the messages that assert identity that are passed from the IdP to the SP. In SAML, one identity provider may provide SAML assertions to many service providers. Similarly, one SP may rely on and trust assertions from many independent IdPs.

SAML does not specify the method of authentication at the identity provider; it may use a username and password, or other form of authentication, including multi-factor authentication. A directory service such as LDAP, RADIUS, or Active Directory that allows users to log in with a user name and password is a typical source of authentication tokens at an identity provider. ^[3] The popular Internet social networking services also provide identity services that in theory could be used to support SAML exchanges.

Use case

SAML Web Browser SSO (Service Provider initiated authentication):

1. Request the target resource at the SP.

   The principal (via an HTTP user agent) requests a target resource at the service provider: https://sp.example.com/myresource

   The service provider performs a security check on behalf of the target resource. If a valid security context at the service provider already exists, skip steps 2–7.

2. Redirect to the SSO Service at the IdP.

   The service provider determines the user's preferred identity provider (by unspecified means) and redirects the user agent to the SSO Service at the identity provider: https://idp.example.org/SAML2/SSO/Redirect?SAMLRequest=request

   The value of the SAMLRequest parameter is the Base64 encoding of a deflated <samlp:AuthnRequest> element.

3. Request the SSO Service at the IdP.

   The user agent issues a GET request to the SSO service at the identity provider where the value of the SAMLRequest parameter is taken from the URL query string at step 2. The SSO service processes the AuthnRequest and performs a security check. If the user does not have a valid security context, the identity provider identifies the user (details omitted).

4. Respond with an XHTML form.

   The SSO service validates the request and responds with a document containing an XHTML form:

     <form method="post" action="https://sp.example.com/SAML2/SSO/POST" ...>
       <input type="hidden" name="SAMLResponse" value="response" />
       ...
       <input type="submit" value="Submit" />
     </form>
   

   The value of the SAMLResponse parameter is the base64 encoding of a <samlp:Response> element.

5. Request the Assertion Consumer Service at the SP.

   The user agent issues a POST request to the assertion consumer service at the service provider. The value of the SAMLResponse parameter is taken from the XHTML form at step 4.

6. Redirect to the target resource.

   The assertion consumer service processes the response, creates a security context at the service provider and redirects the user agent to the target resource.

7. Request the target resource at the SP again.

   The user agent requests the target resource at the service provider (again): https://sp.example.com/myresource

8. Respond with requested resource.

Since a security context exists, the service provider returns the resource to the user agent.

Control Tower SAML Integration

Security profiles

Two security profiles for SAML are supported: PKIX and MetaIOP.

The desired profile is specified in the SAML metadata file.

• In case of PKIX, the java.security.cert package is utilized for assertion and validation of the certificates. It implements RFC 5280.
• In case of MetaIOP, trusted certificates are not mandatory. Other mechanisms are used for validation (e.g. explicitly supplying the keys to trust).

Related documentation:

• Package java.security.cert
• Configuring SAML Extension. Security profiles

note

SSO properties are migrated from workfusion.xml to <TOMCAT_HOME>/conf/workfusion.properties and Secure Storage.

Application properties

Property Name	Property Name before 8.4 version	Value	Description
wf.sso.saml.enable	wf/sso/saml/enable	true	Enables or disables SAML 2.0 protocol for Control Tower. Accepted values: true/false
wf.sso.saml.entity.base.url	wf/sso/saml/entityBaseURL	https://HOSTNAME/workfusion	Base url of Workfusion SAML provider.
wf.sso.saml.response.skew	wf/sso/saml/responseSkew	60	Maximum difference between local time and time of the assertion creation which still allows message to be processed. Basically determines maximum difference between clocks of the IDP and SP machines. Defaults to 60 (seconds)

workfusion.properties sample:

# option to enable/disable SSO authentication
wf.sso.saml.enable=true

# base url used during generation SP metadata
wf.sso.saml.entity.base.url=https://HOSTNAME/workfusion

# response skew in seconds
wf.sso.saml.response.skew=60

Secure properties

Property Name	Property Name before 8.4 version	Value	Description
wf.sso.saml.idp.file.metadata	wf/sso/saml/idp/file/metadata	/path/to/local/meta	Local path to a file with IdP metadata parameters.
wf.sso.saml.idp.metadata	wf/sso/saml/idp/metadata	https://SAML_SERVICE_URL/idp/sso	URL that points to a file with IdP metadata parameters. Should be provided by customer. Attention! This parameter is an alternative to wf.sso.saml.idp.file.metadata, which is a recommended option.
wf.sso.saml.sp.metadata	wf/sso/saml/sp/metadata	workfusion-metadata-id	A unique string. ID of Service Provider.
wf.sso.saml.username.attribute	wf/sso/saml/username/attribute	uid	Name of attribute that will be used for authentication. uid for LDAP, sAMAcountName for Active Directory. Should be provided by customer.

Secure Storage sample properties:

# url to IdP metadata, use url or file
#wf.sso.saml.idp.metadata=none

# path to IdP metadata file
wf.sso.saml.idp.file.metadata=/path/to/local/metadata

# some unique name
wf.sso.saml.sp.metadata=wf-sp-hostname

# the name of an attribute taken from IdP response that contains username
wf.sso.saml.username.attribute=uid

Configuration steps

1. Create in Control Tower admin record that fits your SSO account.
2. Update workfusion.properties as shown above.
3. Restart tomcat.
4. Navigate to URL https://WORKFUSION_HOSTNAME/workfusion/saml/metadata. Metadata file will be downloaded. Add it to your SSO Identity Provider.
5. Navigate to Workfusion Login Page. From now you'll be redirected to your Identity Provider Login Page. Enter your admin account and you are in.

User authentication and authorization

• This implementation assumes that the user who is going to log in via the identity provider (IdP) already exists in Control Tower.

• Admin user who is responsible for creation new users and assigning privileges should be created at first directly through database.

• Admin user must create new users with usernames that already exists in IdP.

• If user that is deleted, disabled or doesn't exist in WorkFusion trying to login he will be redirected to WF login failed screen with a validation message.

  

• User authorization takes place on the WorkFusion side. Admin user can manage user roles.

IdP configuration

Assertion Consumer Service, EntityID and Public Key can be found in the metadata XML file.

Service Provider metadata can be downloaded by the URL https://<instance>/workfusion/saml/metadata (for example, https://SOMESITE.WORKFUSION_HOSTNAME/workfusion/saml/metadata).

LDAP / AD authorization

Control Tower supports SSO authentication together with LDAP / AD authorization. For details on how to enable LDAP / AD auhotization and map user groups is described in LDAP / AD Integration.

IpP > SP (CT) > LDAP sequence diagram

WorkSpace SAML integration

SSO properties are migrated from workspace.xml to <TOMCAT_HOME>/conf/workspace.properties and Secure Storage.

Application properties

Property Name	Property Name before 8.4 version	Value	Description
ws.sso.saml.enable	cv/sso/saml/enable	true	Enables or disables SAML 2.0 protocol for Control Tower. Accepted values: true/false
ws.sso.saml.entity.base.url	cv/sso/saml/entityBaseURL	https://HOSTNAME/workspace or https://HOSTNAME/workspace-sandbox	Base url of Workfusion SAML provider.
ws.sso.saml.response.skew	cv/sso/saml/responseSkew	60	Maximum difference between local time and time of the assertion creation which still allows message to be processed. Basically determines maximum difference between clocks of the IDP and SP machines. Defaults to 60 (seconds)

workspace.properties (workspace-sandbox.properties) sample:

# option to enable/disable SSO authentication
ws.sso.saml.enable=true
 
# base url used during generation SP metadata
ws.sso.saml.entity.base.url=https://WORKSPACE_HOSTNAME/workfusion

# response skew in seconds
ws.sso.saml.response.skew=60

Secure properties

Property Name	Property Name before 8.4 version	Value	Description
ws.sso.saml.idp.file.metadata	cv/sso/saml/idp/file/metadata	/path/to/local/meta	Path to file with IdP metadata parameters.
ws.sso.saml.idp.metadata	cv/sso/saml/idp/metadata	none	URL that points to a file with IdP metadata parameters. Should be provided by customer. Attention! This parameter is an alternative to wf.sso.saml.idp.file.metadata, which is a recommended option.
ws.sso.saml.sp.metadata	cv/sso/saml/sp/metadata	ws-sp-hostname	A unique string. ID of Service Provider, for example, https://<instance>/workspace/saml/metadata
ws.sso.saml.username.attribute	cv/sso/saml/username/attribute	mail	Name of attribute that will be used for authentication.

Secure Storage sample properties:

# url to IdP metadata, use url or file
#ws.sso.saml.idp.metadata=none

# path to IdP metadata file
ws.sso.saml.idp.file.metadata=/path/to/local/metadata

# some unique name
ws.sso.saml.sp.metadata=ws-sp-hostname
 
# the name of an attribute taken from IdP response that contains user's email address
ws.sso.saml.username.attribute=mail

At least one of the "idp" properties should be set. Otherwise, you'll get the "No IdP was configured" page.

User authentication and authorization

• This implementation assumes that the user who is going to log in via the identity provider (IdP) already exists in WorkSpace.
• Requester should be created at first directly through database. Their email in IdP must be equal to username in WorkSpace.
• A Worker can get registered by himself. His/her email in IdP must be equal to the username in WorkSpace.
• If the user that is deleted, disabled or doesn't exist in WorkSpace, while trying to login via IdP the user will be redirected to index page with a validation message.
• A disabled (non active) user can be activated by email or by a Requester.

IdP configuration

Assertion Consumer Service, EntityID and Public Key can be found in metadata xml file.

Service Provider metadata can be downloaded by the URL https://<instance>/workspace/saml/metadata.