10.0

Edit

Integrate SSO

important

Before starting the SSO integration, request the IdP metadata (file or URL) from the security team.

SAML 2.0

Security Assertion Markup Language (SAML) 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)
  • 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, that means it can decide, whether or not to perform some service for the connected principal.

Before delivering the identity assertion to the SP, the IdP can 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

The following security profiles for SAML are supported:

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

The desired profile is specified in the SAML metadata file.

Related documentation:

Package java.security.cert

Configuring SAML Extension. Security profiles

Application Properties

<TOMCAT_HOME>/conf/workfusion.properties

Property NameValueDescription
wf.sso.saml.enabletrueEnables or disables SSO (SAML 2.0 protocol) authentification for Control Tower. Accepted values: true/false
wf.sso.saml.entity.base.urlhttps://HOSTNAME/workfusionBase URL of Control Tower (Service Provider). Used in SP metadata. (see Service Provider metadata example)
wf.sso.saml.response.skew60Maximum 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

These properties are placed to Secure Storage.

Property NameValueDescription
wf.sso.saml.idp.file.metadata/path/to/local/metaLocal path to a file with IdP metadata parameters.
wf.sso.saml.idp.metadatahttps://SAML_SERVICE_URL/idp/ssoURL that points to a file with IdP metadata parameters. Must be provided by a customer.

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

wf.sso.saml.sp.metadataworkfusion-metadata-idA unique string. ID of Service Provider.
wf.sso.saml.username.attributeuidName of attribute that will be used for authentication.
  • uid for LDAP
  • sAMAcountName for Active Directory

Must 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

Service Provider metadata example

For example Control Tower is installed and available by URL https://example-host-name/workfusion

Metadata for this Service Provider can be generated and downloaded by URL https://example-host-name/workfusion/saml/metadata

SP metadata example

Meta

<EntityDescriptor/> has attributes with Service Provider ID and entityID. These attributes are configured through property wf.sso.saml.sp.metadata.

Identity Provider metadata example

Usually IdP metadata is provided by a security team. It can be a file or URL.

The file should be placed on the application server (SP) and be accessible for Service Provider (Control Tower). It is configured via the property wf.sso.saml.idp.file.metadata.

If URL provided, it can be configured via wf.sso.saml.idp.metadata.

Both properties wf.sso.saml.idp.file.metadata and wf.sso.saml.idp.metadata cannot be configured at the same time.

Show IdP metada example

<IDPSSODescriptor/>** must contain information about login/logout endpoints: SingleSignOnService, SingleLogoutService, and attributes' description – saml:Attribute.

<saml:Attribute/> is the username attribute name and must be mapped via wf.sso.saml.username.attribute/ws.sso.saml.username.attribute in Secure Storage. (for example, wf.sso.saml.username.attribute=ACCOUNT). The value of this mapped attribute in IdP response will be used for authorization.

Identity Provider Authentication Response

After a user logs in on the IdP side, the server sends a response to SP (CT/WS) and this response must include username attributes configured (if not encrypted) in wf.sso.saml.username.attribute or ws.sso.saml.username.attribute.

How to decrypt SAML Response

To catch SamlResponse from IdP, use a debuger (press F12 to open it) in your browser and then try to login . Then select the SSO name among all names of the Network tab and there will be present decoded SamlResponse. Copy this value and decode it using https://www.samltool.com/decode.php tool.

  • Example of the IdP response with not encrypted data:

The Destination attribute in Response must contain an URL that leads to the <AssertionConsumerService/> tag into SP metadata.

The <saml:Audience/> tag from <saml:AudienceRestriction/> must contain a value of wf.sso.saml.sp.metadata/ws.sso.saml.sp.metatdata from vault (depends on component you are configuring SSO for).

<saml:AtributeValue> is "someusername" and will be used for authentication on the SP side (if configuration is wf.sso.saml.username.attribute=uid).

Example

wf.sso.saml.sp.metadata = test.workfsuin.com_workspace-sandbox
--------------------------------------------------------------
In this case, Audience will look like:

<saml:AudienceRestriction xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion">
        <saml:Audience>test.workfusion.com_workspace-sandbox</saml:Audience>
</saml:AudienceRestriction>

Example of the IdP response with the encrypted data:

IdP and SP metadata description

TagSourceDescription
EntityDescriptorIdP/SP metadatamain metadata's tag with ID/EntityID attributes
IDPSSODescriptorIdP metadataIdP configuration description
SPSSODescriptorSP metadataSP configuration description
SingleSignOnServiceIdP metadataEndpoint to sign on
SingleLogoutServiceIdP/SP metadataEndpoint to sign out
AssertionConsumerServiceSP metadataSP endpoint to assert response from IdP side
saml:AtributeIdP metadata/responseAttribute description goes from IdP side
saml:AtributeValueIdP responseAttribute value
saml:AudienceRestrictionIdP responseContainer for saml:Audience tag
saml:AudienceIdP responseSP EntityID for which the response is sent (used in response Assertion)
samlp:StatusCodeIdP responseResponse status, success example value (urn:oasis:names:tc:SAML:2.0:status:Success)

Configure SSO

  1. Before enabling SSO, in Control Tower, create a user with the Administrator role and a name that is suitable for your SSO account.

    Create user

  2. Configure application and secure properties to enable SSO:

    # workfusion.properties file
wf.sso.saml.enable=true
wf.sso.saml.entity.base.url=https://control-tower-host/workfusion
# Secure Storage
wf.sso.saml.idp.file.metadata=/path/to/ipd/metadata/provided/by/security/team
wf.sso.saml.sp.metadata=unique-service-provider-name
wf.sso.saml.username.attribute=ACCOUNT //the name of the attribute into SSO response with username, usually described in IdP metadata file.

  3. Restart the Application server.

  4. Go to https://control-tower-host/workfusion/saml/metadata. The metadata file will be downloaded. Send it to security team to be added to Identity Provider (SSO server).

  5. Open any CT page. From now you'll be redirected to your Identity Provider Login Page. Enter your account.

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

  • The Admin user who is responsible for creation new users and assigning privileges must be primarily created directly via database.

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

  • If a deleted, disabled, or non-existing user tries to log in, they will be redirected to the WorkFusion login failed screen with a validation message.

    Login fail

  • Users are authorized on the WorkFusion side. The 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

For information on enabling LDAP and AD auhotization, and mappping user groups, see LDAP and AD integration

WorkSpace SAML Integration

Application Properties

Property NameValueDescription
ws.sso.saml.enabletrueEnables or disables SAML 2.0 protocol for Control Tower. Accepted values: true and false
ws.sso.saml.entity.base.urlhttps://HOSTNAME/workspace
or
https://HOSTNAME/workspace-sandbox		Base url of Workfusion SAML provider
ws.sso.saml.response.skew60Maximum difference between the local time and the time of the assertion creation, which still allows a message to be processed.

Basically determines maximum difference between clocks of the IDP and SP machines. By default, 60 (seconds)

Sample of workspace.properties (workspace-sandbox.properties)

# 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 NameValueDescription
ws.sso.saml.idp.file.metadata/path/to/local/metaPath to file with IdP metadata parameters.
ws.sso.saml.idp.metadatanoneURL that points to a file with IdP metadata parameters. Must be provided by a customer.

This parameter is an alternative to wf.sso.saml.idp.file.metadata, which is a recommended option.
ws.sso.saml.sp.metadataws-sp-hostnameA unique string. ID of Service Provider, for example, https://<instance>/workspace/saml/metadata
ws.sso.saml.username.attributemailA name of the 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
note

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

User Authentication and Authorization

  • This implementation assumes that the user that is going to log in via the identity provider (IdP)** already exists in WorkSpace.
  • A requester must be primarily created directly via the database.The user's email in IdP must be the same as the username in WorkSpace.
  • A Worker can get registered by himself. The email in IdP must be the same as the username in WorkSpace.
  • If a deleted, disabled, or non-existing user tries to log in to Workspace, they will be redirected to the the 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.

← OCR Migration NotesNext →