9.1

Edit

SAML integration

SAML 2.0

SAML (Security Assertion Maskup 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).

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

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

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

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

  5. Respond with a 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
note

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

Application properties

Property Name Value Description 
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
 
https://HOSTNAME/workfusion
 Base url of Workfusion SAML provider. 
wf.sso.saml.response.skew
 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 Value Description 
wf.sso.saml.idp.file.metadata
 
/path/to/local/meta
 Local path to a file with IdP metadata parameters. (an xml file from their server with IdP metadata parameters) 
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. (This should be an endpoint where auth will be provided. like login.html page for the credential provider,, for example, https://secureaccess.example.com/idp/SSO.saml2)

Attention!

This parameter is an alternative to wf.sso.saml.idp.file.metadata, which is a recommended option.

 
wf.sso.saml.sp.metadata
 workfusion-metadata-id A unique string. ID of Service Provider. (Usually the FQDN of Workfusion app server) 
wf.sso.saml.username.attribute
 
"uid" or "sAMAccountName" or some custom value
 Name of attribute that will be used for authentication. uid for LDAP, sAMAccountName for Active Directory. Should be provided by customer, could be something else.

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 (Usually the FQDN of Workfusion app server)
wf.sso.saml.sp.metadata=wf-sp-hostname

# the name of an attribute taken from IdP response that contains username
# Usually "uid" for LDAP, "sAMAccountName" for Active Directory. Can be a custom value based on customer's SSO config, example: 
wf.sso.saml.username.attribute=uid

Configuration steps

  1. In Control Tower, create an admin record that fits your SSO account.
  2. Update workfusion.properties as shown above.
  3. Restart Tomcat.
  4. Navigate to https://WORKFUSION_HOSTNAME/workfusion/saml/metadata. A 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 To enable LDAP / AD auhotization and map user groups, see LDAP / AD Integration.

WorkSpace SAML integration

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

Application properties

Property Name Value Description 
ws.sso.saml.enable
 true

Enables or disables SAML 2.0 protocol for Control Tower. Accepted values: true/false

 
ws.sso.saml.entity.base.url
 
https://HOSTNAME/workspace

or

https://HOSTNAME/workspace-sandbox
 Base url of Workfusion SAML provider. 
ws.sso.saml.response.skew
 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 Value Description 
ws.sso.saml.idp.file.metadata
 
/path/to/local/meta
 Path to file with IdP metadata parameters. 
ws.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 the recommended option. The "idp.file" is an xml file from their auth server with IdP metadata parameters.

 
ws.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
 
mail
 Name of attribute that will be used for authentication.

Secure Storage sample properties:

# url to IdP metadata
# Comment out the ws.sso.saml.idp.file.metadata if you choose this URL option, only one may be used.
# ws.sso.saml.idp.metadata=https://secureaccess.example.com/idp/SSO.saml2

# path to IdP metadata file, can be curl'ed from customer SSO endpoint,, for example, curl -O https://secureaccess.example.com/idp/SSO.saml2
# Comment out the ws.sso.saml.idp.metadata if you use this option, only one may be used.
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
note

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 themselves. Their 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 a metadata XML file

You can download Service Provider metadata by the URL: https://<instance>/workspace/saml/metadata

← PreviousNext →