SAML 2.0 (Federated Identity) Support

Process Director supports SAML-based authentication for web single sign-on (SSO).  SAML is an XML-based framework for communicating user authentication, entitlement, and attribute information.

Process Director accepts SAML 2.0 assertions regarding the identity, attributes, and entitlements of a user, from a federated Identity Provider (e.g. OpenAM or the open source version of OpenSSO).

The basic SSO model is shown in following diagram. A user authenticates at the identity provider and is subsequently appropriately recognized (and given corresponding access or service) at the service provider (Process Director).

 

Authentication Options #

Process Director supports federated authentication. Federated authentication doesn't validate the user's actual password on Process Director. Instead, Process Director receives a SAML assertion in an HTTP POST request. The SAML assertion has a limited validity period, contains a unique identifier, and can be digitally signed. If the assertion is still within its validity period, has an identifier that hasn't been used before, and has a valid signature from a trusted identity provider, the user is granted access. If the assertion fails for any reason, the user is informed that their credentials are invalid.

Implementation Details #

The transaction from an identity provider (IP) to Process Director is called a SAML assertion. Process Director assumes that all data contained in the assertion from the identity provider is valid. The structure of the SAML assertion is defined by an XML schema that is specified by the OASIS SAML standard and contains header information, the subject and statements about the subject in the form of attributes and conditions such as a start and logout URL. The SAML assertions will contain a Federated ID from the identity provider; this must be mapped to a user in Process Director (see below for more information on this mapping).

There is an online SAML tool that will assist you in creating the XML metadata file that can be consumed by your IP. This tool is located at https://www.samltool.com/sp_metadata.php.

Web browser SSO is SAML's most widely used feature and is typically used in conjunction with the HTTP POST binding and authentication request protocol. There are two important use cases for SAML: Identity Provider Initiated Login, where a user starts directly at their identity provider, logs in, and is then redirected to a landing page at the service provider; and Service Provider Initiated Login, where a user starts by clicking a link to the service provider (e.g. bookmark, email link, etc) and is temporarily redirected to the identity provider for authentication, then returned to the link they initially requested.

Process Director supports Service Provider Initiated Logins, where a user starts by clicking a link to a Process Director object (e.g. home page, Form, etc) and is temporarily redirected to the identity provider for authentication, then returned to the link within Process Director they initially requested.

Process Director Configuration Settings #

The user authentication configuration options support the SAML SSO configuration. The SAML configuration information includes:

• SAML Issuer
• SAML Provider Name
• SAML IP Certificate
• SAML URL
• SAML Logoff Page
• SAML Request Type
• SAML Response Type

For Process Director, these are the possible ACS URL configurations:

• https://HOSTNAME/login_saml.aspx?SAMLRESPONSE=1&usertype=&reauth=&f=
• https://HOSTNAME/login_saml.aspx?SAMLRESPONSE=1&usertype=1&reauth=&f=
• https://HOSTNAME/login_saml.aspx?SAMLRESPONSE=1&usertype=4&reauth=&f=

If using re-authentication as part of the electronic signatures these additional URLs are needed:

• https://HOSTNAME/login_saml.aspx?SAMLRESPONSE=1&usertype=&reauth=1&f=
• https://HOSTNAME/login_saml.aspx?SAMLRESPONSE=1&usertype=1&reauth=1&f=
• https://HOSTNAME/login_saml.aspx?SAMLRESPONSE=1&usertype=4&reauth=1&f=

The usertype URL parameter can be blank, but also accepts a value that corresponds to the correct authentication type for the user, as specified by the nAuditType enum in the Process Director database, e.g., 1 for a Windows user, 4 for a SAML user, etc., depending on wether your system requires specific identification of user types.

Additional information is configured to establish the trust relationship with the identity provider. This configuration specifies what element in the SAML assertion identifies the user, and how that user ID will be mapped to the Process Director users.

User Mappings #

When setting up SAML authentication, you'll establish an association between the identity provider and Process Director, forming a federation. When configuring the identity provider, you must determine the unique identifier that will be passed to Process Director as part of the assertion. This is what will uniquely identify the user to Process Director.

This value must be unique for all users in Process Director. Process Director also must be able to determine if this user is held by that part of company's identity infrastructure (e.g. AD, LDAP server) synchronized to the server. If so, then all needed information about the user will already be known.

If the user isn't found, it can be automatically be created in the Process Director database. If there is any information contained in the SAML assertion that indicates the source of this user (e.g. from an AD server), Process Director can use that information to populate the users email address and user name. If that information doesn't exist, this user information will have to be entered from within the Process Director administrative interfaces.

When SAML integration is enabled, any request to a protected page or login to Process Director will automatically be redirected to the SAML Identity Provider. To use built-in or Windows authentication while SAML support is enabled, add the URL parameter skipsaml=1 to the login.aspx page. When this parameter is present, SAML integration won't be used for that login.

Configuration #

To configure SAML support, the following variables can be configured in the Process Director custom vars file at /custom/vars.cs.ascx, in the PreSetSystemVars section. Attribute names can be configured using the Form Name or the Friendly Name.

VARIABLE NAME	DESCRIPTION
SAML_Enable	Is SAML integration enabled?
SAML_URL	The URL of the SAML Identity Provider
SAML_Request_Type	SAMLReqType.HTTPRedirect (default) SAMLReqType.HTTPPost SAMLReqType.HTTPArtifact
SAML_Response_Type	SAMLRespType.HTTPPost (default) SAMLRespType.HTTPArtifact
SAML_Issuer	The URL of the SAML issuer.
SAML_Artifact_URL	Optional Identity Provider artifact URL
SAML_My_PFX	Optional path to local PFX file to sign SAML requests
SAML_My_PFXPassword	Optional password of local PFX file to sign SAML requests
SAML_My_Certificate	Optional path to Process Director public certificate file (.cer)
SAML_IP_Certificate	Optional path of Identity Provider public certificate file to validate entire SAML response (.cer)
SAML_IP_AssertionCertificate	Optional path of Identity Provider public certificate file to validate assertions in SAML response (.cer)
SAML_Attrib_GUID	Optional name of attribute containing User GUID
SAML_Attrib_UserID	Optional name of attribute containing User UserID. It will match with an existing user in the system using the EXTERNAL GUID attribute first (if configured), and the userID attribute next. If not set, it defaults to the SAML assertion’s “subject”.
SAML_Attrib_UserName	Optional name of attribute containing User UserName
SAML_Attrib_Email	Optional name of attribute containing User Email
SAML_Attrib_Groups	Optional name of attribute containing User Groups
SAML_Attrib_CustomString	Optional name of attribute containing the custom string to store in user record
SAML_Attrib_CustomNumber	Optional name of attribute containing the custom number to store in user record
SAML_Attrib_CustomDate	Optional name of attribute containing the custom date/time to store in user record
CustomLogoffPage	Optional URL to navigate to after logoff

A sample configuration in the custom vars file might look as follows:

// Called BEFORE database initialized
public override void PreSetSystemVars(BPLogix.WorkflowDirector.SDK.bp bp)
{
    bp.Vars.SAML_Enable = true;
    bp.Vars.SAML_IP_Certificate = @"C:\Program Files\BP Logix\cert.cer";
    bp.Vars.SAML_URL =
        "https://adfs.company.com/adfs/ls/idpinitiatedsignon.aspx?logintoRP=
         https%3a%2f%2fcloud.bplogix.net";
    bp.Vars.CustomLogoffPage = "https://signin.company.com/";
    bp.Vars.SAML_Request_Type = SAMLReqType.HTTPRedirect;
    bp.Vars.SAML_Response_Type = SAMLRespType.HTTPPost;
    bp.Vars.SAML_Issuer = "https://cloud.bplogix.net";
    bp.Vars.SAML_ProviderName = "https://cloud.bplogix.net";
    bp.Vars.SAML_Attrib_GUID = "SAML-Account-ID";
    bp.Vars.SAML_Attrib_UserID = "SAML-Account-Name";
    bp.Vars.SAML_Attrib_UserName = "DisplayName";
    bp.Vars.SAML_Attrib_Email = "Email@email.address";
    bp.Vars.SAML_Attrib_Groups = "Groups";
    // For Azure Single Sign-Out (PD v6.0.100 and higher)
    bp.Vars.SAML_Enable_SLO = true;
}

Azure Single Sign-Out #

For Process Director v6.0.100 and higher, Azure Single Sign-Out has been implemented for installations that use Azure Based SAML logins. This feature will, when logging out of Process Director, also completely log the user off the SAML Identity Provider (Azure). A new Custom Variable, SAML_Enable_SLO, is used to implement the Single Sign-Out feature.

To fully implement this feature, the LogoutURL setting in Azure must be set to:

https://<processDirectorUrl>/login.aspx?skipsaml=1

...to specify where to be redirected after logging out of SAML.