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, for example, a username and a password, 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.
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):
Request target resource at 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.
Redirect to SSO Service at 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.
Request SSO Service at 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).
Respond with 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.
Request Assertion Consumer Service at 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.
Redirect to 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.
Request target resource at SP again
The user agent requests the target resource at the service provider (again): https://sp.example.com/myresource
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 – 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
important
SSO properties are migrated from workfusion.xml to <TOMCAT_HOME>/conf/workfusion.properties and Secure Storage.
Application properties
| Property Name | Value | Description |
|---|---|---|
|
true |
Enables or disables SAML 2.0 protocol for Control Tower. Accepted values: true/false |
|
|
Base url of Workfusion SAML provider. |
|
60 |
Maximum difference between local time and time of the assertion creation which still allows message to be processed. |
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 |
|---|---|---|
|
|
Local path to a file with IdP metadata parameters. |
|
|
URL that points to a file with IdP metadata parameters. Should be provided by customer. Attention! This parameter is an alternative to |
|
workfusion-metadata-id |
A unique string. ID of Service Provider. |
|
|
Name of attribute that will be used for authentication. u id 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
- In Control Tower, create an admin record that fits your SSO account.
- Update
workfusion.propertiesas shown above. - Restart tomcat.
- Navigate to https://WORKFUSION_HOSTNAME/workfusion/saml/metadata. A metadata file will be downloaded. Add it to your SSO Identity Provider.
- 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 WorkFusion 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 and AD authorization
Control Tower supports SSO authentication together with LDAP/AD authorization. The procedure on how to enable LDAP/AD auhotization and map user groups is described here LDAP/AD Integration.
WorkSpace SAML Integration
important
SSO properties are migrated from workspace.xml to <TOMCAT_HOME>/conf/workspace.properties and Secure Storage.
Application Properties
| Property Name | Value | Description |
|---|---|---|
|
true |
Enables or disables SAML 2.0 protocol for Control Tower. Accepted values: true/false |
|
or |
Base url of Workfusion SAML provider. |
|
60 |
Maximum difference between local time and time of the assertion creation which still allows message to be processed. |
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 |
|---|---|---|
|
|
Path to file with IdP metadata parameters. |
|
|
URL that points to a file with IdP metadata parameters. Should be provided by customer. Attention! This parameter is an alternative to |
|
|
A unique string. ID of Service Provider, for example, https://<instance>/workspace/saml/metadata |
|
|
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
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. The email in IdP must be equal to the username in WorkSpace.
- A Worker can get registered by himself. The 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.
Service Provider metadata can be downloaded by the URL: https://<instance>/workspace/saml/metadata