Documents reference for  SAML Authentication with MDM.

SAML Authentication with MDM

Product: TIBCO MASTER DATA MANAGEMENT Version: 9.0.0 or higher OS: ALL

 The MDM supportes SAML SSO authentication for web service, but MDM document does not have stpe/information reagarding SAML.

  SAML Integration with CIM for WS Security for MDM 9.1.0  is mentioned below  also you can find documentation as per your install version at         "$MQ_COMMON_DIR\standard\samples\authentication\SAML" 

About SAML :
===========

-Security Assertion Markup Language (SAML) is an XML-based framework for communicating user authentication, entitlement, and attribute information.
- SAML is being applied in a number of different ways, one of which is securing Web services. SAML assertions can be used within SOAP messages in order to carry security and identity information between actors in Web service transactions.
- An assertion is a package of information that supplies one or more statements made by a SAML authority

    Below is a representation of the parts/elements of a SAML 2.0 assertion:
     1.<saml:Assertion> element contains the following subelements:
     2. <saml:Issuer> element, which contains the unique identifier of the identity provider
     3.<ds:Signature> element, which contains an integrity-preserving digital signature (not shown) over the <saml:Assertion> element
     4.<saml:Subject> element, which identifies the authenticated principal (the logical name of the  “user”)
     5.<saml:Conditions> element, which gives the conditions under which the assertion is to be considered valid
     6.<saml:AttributeStatement> element, which asserts multi-valued attributes associated with the authenticated principal
     7.<saml:AuthnStatement> element, which describes the act of authentication at the identity provider
     
    Requirement: Create a new login module which handles SAML assertions in WS requests, and processes authentication/authorization based on it. 
    ============
    
    Scope of POC: To create a login module to process an incoming WS request with SAML assertion. (i.e CIM-related changes)
    ============
    
    Not in Scope:  Changes/Configurations required to generate/issue a SAML assertion. (i.e “SAML issuer” related changes). 
    =============


Implementation:
================

This note describes the steps to implement a Login Module which supports SAML assertions in WS requests. The module consists of 2 parts:

The Header Extractor (SAMLHeaderExtractor)
The Login handler (SAMLLoginModule)

" The diagram attached shows the sequence of steps taking place – when a user wants to access CIM through secured WS requests."



Changes to ConfigValues.xml:
===========================

1). Under the property name – “Web Service SOAP Header Extractor”; change the value to “SAMLHeaderExtractor” (including package name).

       <ConfValue description="This property is used to specify Header Extractor for WebService. the default value is SoapHeaderExtractor" name="Webservice Soap             Header Extractor" propname= "com.tibco.cim.authentication.webservice.headerExtractor" sinceVersion="8.2" visibility="Advanced">
        <ConfString default= "com.tibco.cim.authentication.webservice.DefaultSoapHeaderExtractor" v                       value="com.tibco.cim.authentication.webservice.SAMLHeaderExtractor"/>
          </ConfValue>
        
2). For “AuthenticationType” – change the value to “SAML”.

<Group typeName="AuthenticationType" typeValue="SAML">
                

3). Create a new <Item name= “SAML”> element under “AuthenticationType” – which will represent the configurations,init class, custom properties required for this new login module. (See below)

            <Item name="SAML">
              a. <ConfValue description="This value indicates the authentication method. No value means that the default/LDAP authentication is used." name="Authentication Type" propname= com.tibco.cim.init.AuthenticationManager.authentication" readonly="true" sinceVersion="7.0" visibility="Advanced">
                <ConfString default="saml" value="saml"/>
               </ConfValue>
             b. <ConfValue description="Java Class implementing the Custom Authentication method." name="SAML Authentication Init Class" propname="com.tibco.cim.init.AuthenticationManager.authentication.saml.class" sinceVersion="7.0" visibility="Advanced">
                <ConfString default="" value="com.tibco.mdm.directory.security.authentication.SAMLLoginModule"/>
              </ConfValue>
             c. <ConfValue description="Java Class implementing the Custom Authentication method." name="SAML Issuers list" propname="authentication.saml.issuers" sinceVersion="8.2" visibility="Advanced">
                <ConfString default="urn:www.tibco.com" value="urn:www.tibco.com , urn:www.test.com"/>
               </ConfValue>
            </Item>

Currently, there are 3 properties defined under this item:
Represents the short-hand internal notation for representing/accessing this login module
Represents the Java class implementing this login module.
Represents the list of issuers trusted by CIM.

If more custom attributes need to be checked for – against predefined values (signatures, certificates, custom passwords etc.); add more properties with appropriate propname. Use the same propname in the code – to retrieve the values from here while processing the request.

PLEASE REFER TO SAMPLE OF CUSTOM PROPERTIES DEFINED in ConfigValues_SAML.xml
=============================================================================

Mapping external roles to CIM:
=================================
External roles are mapped to CIM internal roles via entries in the rolemap.prop file. Sample entry in this file looks like –

TESTGROUP1= Admin, Work Supervisor
TESTGROUP2= Support Engineer




Implementation Details :
=======================

1.* User sends its credentials to SAML Issuer component and requests to issue a SAML assertion. Alternately an incoming web service request will be intercepted by the policy server and a SAML assertion could be inserted into the web service.

2.* SAML issuing authority verifies, authenticates and authorizes the credentials; and issues an assertion verifying the credentials. This assertion is valid for a particular timeframe.

3. WS-User appends the assertion in the SOAP header of the WS-Request; and sends the request to CIM.

4. CIM receives the request; forwards it to the SAMLHeaderExtractor. SAMLHeaderExtractor is a custom SOAP header extractor plugged into CIM using configuration. This is a new feature in CIM 8.2.
The header extractor class receives the request; extracts the SOAP header element (which contains the SAML assertion) and retrieves all the required values/attributes from the assertion using Xpath. Note that other techniques can also be used to retrieve/parse the assertion.

            Example xpath: 
            ==============

                 //saml2:AttributeStatement//saml2:Attribute[@Name='Role']

            Here, we’re retrieving “Attribute” element having an attribute named “Role”; which is a child element of “AttributeStatement” element. All paths are relative to “wsse:Security” element.

            On similar lines, values such as Issuer, Timestamp validity (NotOnorBefore, NotOnorAfter), username,enterprise,roles, other user-defined attributes can be retrieved.

            In this POC – we are assuming the enterpriseand roles are provided in the assertion attributes; while username is provided as “NameID” of the “Subject” element

            The values are put into a header map; and the request is forwarded. After some intermediate session processing; the request is forwarded to the main login class – SAMLLoginModule.

            Note1: SAML attributes are user-defined and can be configured. External roles are mapped to CIM using rolemap.prop file.

            Note2: In the POC; all user-related fields are not covered in the SAMLHeaderExtractor. These may be added as per requirement – on same lines as extracting other attributes like “enterprise”, “role”


5. The SAMLLoginModule receives the request and -

The ‘handleWebServiceLogin’ method of this class is called – with a parameter ‘userdetails’ which is a map of headervalues retrieved in HeaderExtractor class. This in-turn calls ‘handleLogin’ method.

This method firstly gets username,roles & enterprise values from map; and calls “validateLogin” method- which checks if the mandatory values of enterprise & username are present or not. No request can be executed if either of these is not present.

Next, the ‘checkAssertion’ method is called – which handles the “trust verification” and assertion validity checks of the assertion. 

Trust Verification:  
=====================
We need to establish the trust between CIM and the assertion issuing authority. In the POC; this is done by checking if the value of “issuer” (retrieved from headerMap) corresponds to a list of issuers already known to CIM (entered in ConfigValues.xml).

Once the trust is established; the validity of the assertion is checked (using date values of “NotOnorBefore” and “NotOnOrAfter”). If the current date doesn’t fall between the above mentioned values; the assertion is deemed as expired or invalid.

If any of the checks above fail; the assertion is deemed invalid; an exception is logged and the request is not executed

Further checks can be done – by retrieving the signature,token, etc present in the assertion (via xpath in HeaderExtractor); and validating them against keystores/certificates/tokens already present in or known to CIM. This piece of code should go in “checkAssertion” method. External jars/api’s to take care of signature verification may also be used. If the checking has to be done against a file/keystore present on disk; the path of the resource can be added as a property in ConfigValues.xml (covered later).

Step 5:
=========
Once ‘checkAssertion’ returns true – the username and enterprise values are validated against CIM internal data.

Following this – “updateUser” method (already existing in CIM) is called if the flag to allow “modify users” is set. In this method – all user-data (retrieved in HeaderExtractor and populated in the map) is checked against CIM data; and is modified is there is any change. For update of roles; external roles are mapped to internal CIM roles via rolemap.prop file. 


6. Finally the request is forwarded to WS-Broker which executes the request. If user details are not found or are changed from existing values; then user details are first added before executing the request.

Note 1: *Steps 1 & 2 are out of POC scope
=======================================
Please follow instructions in " CIM - Sys Admin Guide -> External User Authentication " carefully for getting clearer picture on different types of authentication mechanisms, out-of-box &
custom implementations and samples.   and

Note 2:Required Classes,ConfigCalues.xml can find in the attchements.
======