Layer 7 Access Management

Expand all | Collapse all

Use Powershell to call IM TEWS (SOAP)

  • 1.  Use Powershell to call IM TEWS (SOAP)

    Posted 04-05-2016 12:06 PM

    Hello All,

     

    One of my customers asked a question about using CLI / script processes to on-board legacy/existing users, but also wished to lower business risk for any modifications.

     

    The customer was running the CA Identity Management solution in Production environment with limited # of users to stabilize their business logic / workflows before opening the solution to the broader business community.   After all business validation / performance checks were successful, the customer wished to load user data into their IM solution but not disable any business rules (PX/MX/IdP) while doing so.

    The methodology above is a successful model to isolate high impact challenges/issues due to any incorrect data mappings/business logic; prior to go-live status; over a period to allow full QA validation of 1000's of test scripts.

     

     

    Challenge:  If the customer was to use the IM Bulk Loader Task or IM BLC (Bulk Load Client) Client tool, this process would create the user, at the top tier of the solution, and all IME (IM Environment) business rules would be used.

     

    Since these users already exist within various userstores, e.g. Active Directory, Mainframe (ACF2/TSS/RACF), Unix/Linux, Databases, Cloud Apps, there is always the chance that an attribute may be changed if the business rules include Provisioning Roles (PR) and Account Templates (AT).  The change may be slight and have no impact, but there is the possibility of change.

     

    Example:  Userstore/endpoint attributes that are quotas may be updated to a higher value, if the Account Template is set to a higher number than what the end user already has, this may be a desired state, but if not, this change is something to avoid or to be addressed in a controlled manner.    We wish to avoid thousands or millions of calls to the help desk for any loss of access or unscheduled change with this very large initial bulk load.

     

     

     

    Goal:   Load 10 million users into the CA IM solution with low business risk for any unscheduled modifications to managed endpoint/userstore accounts using ONLY CLI (command line interface) / script processes.

    - Eliminate data entry via manual input.   Avoid use of UI (IME) or GUI (IMPS Manager UI) for this use-case.

     

    1)   Initial state:

       MX/PX/IdP business rules are active in the IME;  

       Endpoints have already been defined and explored.   Not correlated.  { Validate no correlation to [default user]  }

       PR (Provisioning Roles)/AT (Account Templates) exist and are actively managing production endpoint/userstores with service accounts that have proper access to manage accounts.

     

     

    2)  Load a pre-filtered LDIF file to primary userstore for IM solution (IMCD = IM Corporate User store) of all 10 million users.

    - Pro: User are loaded at the data tier;  IME is unaware of the new users = no business rules are activated

    - Con: Audit record is limited for initial bulk load to Directory logs.

     

     

    3) Use CLI process to call IM TEWS (SOAP) to assign a "NULL" Provisioning Role to the new user.

    -  Pro:  This process will avoid the "Create Event" use-case; and avoid any business logic tied to this event.

    The assignment of the "Null" PR will create an IMPS GU object with all mapped attributes from IMCD:IMPS

    A "null" provisioning role does NOT have an Account Template associated with it.

    -Con:  N/A

    Use an OS supported CLI process that will allow web service calls to be called via scripts.

    - If Linux, use CuRL.    If Windows OS, use Powershell

    [Note:  CuRL may be used on Windows OS, but there is no "trusted" version from Microsoft or other source.

    Suggest recompile source code on MS Windows to avoid any security concerns.]

     

     

    4a) Re-Explore endpoints if needed.

    Note:  If endpoint takes over 1 hour to run in single thread explore process, review using of IMPS CLI / ldapsearch to parallel explore operations on one or more IMPS servers.

    - Recommendation:  Automate via OS scheduler

    Note:  Explore operations will create the Endpoint Account (EA) pointer object in the IMPD (IM Provisioning Directory).

    This "pointer object" is all that is needed for the IM solution to be aware of where the account exists, and which route to take to manage the endpoint account in the managed endpoint/userstore.

    Example using IMPS ldapsearch (modified with four (4) explore option flags) to explore a limited set of users that userID starts with the letter "a" character:

    ldapsearch -h [hostname] -p 20389 -D "eTGlobalUserName=[username],eTGlobalUserContainerName=Global Users,eTNamespaceName=CommonObjects,dc=im,dc=eta" -w [password] -b "eTADSContainerName=Users,eTADSDirectoryName=[directory_name],eTNamespaceName=ActiveDirectory,dc=im,dc=eta" -s sub "(&(eTADSAccountName=a*)(objectclass=*))" eTExploreUpdateEtrust

     

     

    4b) Use IMPS CLI / etautil to create manual correlation scripts

    Avoid using a single threaded process from one single IMPS server.   Create parallel correlation processes.

    Follow the below format for an input file to etautil -

    ADD   BASE   CLASS   ATTRIBUTE  IN  BASE  CLASS  ATTRIBUTE  SEMICOLON

    ADD  eTACFLidContainerName=Accounts,eTACFDirectoryName=MainframeACF2HostA,eTNamespaceName=CA-ACF2,dc=im   eTACFLid  eTACFLidName=LID  IN   'eTGlobalUserContainerName=Global Users,eTNamespaceName=CommonObjects,dc=im'    eTGlobalUser eTGlobalUserName=GUID;

    Pro:  This correlation will now tie (create an inclusion), the endpoint account (EA) to the IMPS Global User (GU).   This will allow the following to occur:

    - Attribute Sync:  Account Status (lock/unlock) & Password sync from top-tier to bottom-tier (endpoints/userstore)

    - Audit Record:  Where a user account exists

    - Deletion Use-Case:   Since the record is now attached, the top tier now has the availability to manage the delete user and all managed endpoint account use-case.

     

     

    5) Use the IMPS CLI / etautil to build the relationship between an Account Template (AT) and the Endpoint Account (EA) pointer object.

    Avoid using a single threaded process from one single IMPS server.   Create parallel correlation processes.

    Follow the below format for an input file to etautil -

    ADD   BASE   CLASS   ATTRIBUTE  IN  BASE  CLASS  ATTRIBUTE  SEMICOLON

    ADD    eTADSOrgUnitName=RUUsers,eTADSOrgUnitName=Russia,eTADSOrgUnitName=EMEA,eTADSOrgUnitName=Regions,eTADSDirectoryName=ADS_Hostname,eTNamespaceName=ActiveDirectory,dc=im   eTADSAccount eTADSAccountName='Abikutova (EXT), Olesjja'  IN   'eTADSPolicyContainerName=Active Directory Policies,eTNamespaceName=CommonObjects,dc=im' eTADSPolicy eTADSPolicyName=ADSContractorPolicy;

    Pro:  This relationship / inclusion will now tie the endpoint account (EA) to an exact Account Template (AT).   This will allow the additional functionality to occur:

    - Attribute Sync:  All managed attributes within the Account Template that use Rule Strings, e.g. %FN%, will now propagate from top-tier to bottom-tier (endpoints/userstore)

     

     

    6) Use the IMPS CLI / etautil to build the relationship between an Global User (GU) and the Provisioning Role (PR).

    Avoid using a single threaded process from one single IMPS server.   Create parallel correlation processes.

    Follow the below format for an input file to etautil -

    ADD   BASE   CLASS   ATTRIBUTE  IN  BASE  CLASS  ATTRIBUTE  SEMICOLON

    ADD   'eTGlobalUserContainerName=Global Users,eTNamespaceName=CommonObjects'   eTGlobalUser eTGlobalUserName=GUID   IN  'eTRoleContainerName=Roles,eTNamespaceName=CommonObjects' eTRole eTRoleName=USContractorRole;

    Pro:  This relationship / inclusion will now tie the Global User (GU) to an exact Provisioning Role (PR).   This will allow the additional functionality to occur:

    - Modify / Delete Use-Case by Role:   The IME (top tier) will now be able to manage the user by Roles; either removal or append to.

    - Audit Record:  The IME (top tier) will now be aware of what Roles the user has to be manage.

    - Sync Operations:   User Sync by Role will now be possible.  Typically used when many endpoints are managed by one (1) roles; and the endpoint lifecycle is changed by one hostname to another hostname.

     

     

    7)  Validation:  Use CLI processes to push changed to the IM Task "Modify User" to validate attribute is mapped correctly and the value will flow from top-tier to bottom-tier.

     

     

     

    MS POWERSHELL EXAMPLE  [ Invoke-WebRequest ]

     

    Example with MS Powershell for CLI on MS Windows to call SOAP web-server using the Invoke-WebRequest module.

    Assumptions:  IME has Web Service enabled in the IME Management Console.   & IM Modify User task is enabled for webservice

    Note:   No SSL nor CA SSO tight integration in example

    Methodology:   Use SOAPUI tool to connect to IME WSDL and validate IM Modify User task is exposed; and then use SOAPUI to validate SOAP Body to submit record.  Validate in IM VST.

    SoapUI | Functional Testing for SOAP and REST APIs

     

     

    The below Powershell script allow three (3) input strings:   UID to be managed,  the IME Service Account that has access to IM Modify User Task; and the Service Account password:

    The script is used to attach a Provisioning Role to a user.   See Step #3 above.

    The SOAP Body was reduced to the minimal XML code needed to meet requirements.

     

    **********************************  Script below  *****************************

    [CmdletBinding()]
    Param(
      [Parameter(Mandatory=$True,Position=1)]
      [string]$accountID,

      [Parameter(Mandatory=$True,Position=2)]
      [string]$adminid,

        [Parameter(Mandatory=$True,Position=3)]
      [string]$adminpassword

    )

    [xml]$SOAP = @"
    <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:wsdl="http://tews6/wsdl">
      <soapenv:Header/>
      <soapenv:Body>
         <wsdl:TaskContext>
            <wsdl:admin_id>$adminid</wsdl:admin_id>
            <wsdl:admin_password>$adminpassword</wsdl:admin_password>
         </wsdl:TaskContext>
         <wsdl:ModifyUser>
            <wsdl:ModifyUserSearch>
               <wsdl:Subject index="?">
                  <wsdl:UID>$accountID</wsdl:UID>
               </wsdl:Subject>
            </wsdl:ModifyUserSearch>
            <wsdl:ModifyUserProvisioningRolesTab>
               <wsdl:UserMemberProvisioningRoles>
                  <wsdl:add index="?">
                     <wsdl:Name>NULL</wsdl:Name>
                  </wsdl:add>
               </wsdl:UserMemberProvisioningRoles>
            </wsdl:ModifyUserProvisioningRolesTab>
         </wsdl:ModifyUser>
      </soapenv:Body>
    </soapenv:Envelope>
    "@

     

    $headers = @{"SOAPAction" = "http://tews6/wsdl"}

    $URI = "http://HOSTNAME_FQDN_HEREi/iam/im/TEWS6/ime_name_here"
    $out = Invoke-WebRequest $uri -Method post -ContentType 'text/xml; charset=utf-8' -Body $SOAP -Headers $headers

    Write-Host "$out"

    **********************************  Script above  *****************************

     

     

    The script above may be adjusted for the four (4) scenarios:

    1)    No Auth; No SSL
    2)    IM Auth Only; No SSL      [Current Script]
    3)    IM Auth Only; SSL enabled
    4)    SM Auth w/Impersonation; SSL enabled

     

     

    1)

    Additional note for step #4a:

    Four (4) Explore Option Flags for IMPS ldapsearch / etautil CLI
    eTExploreUpdateEtrust = Retrieves all managed objects.
    eTExploreCorrelateUsers = Correlates accounts with Global Users using existing ones.
    eTExploreCreateUsers = Creates Global Users as needed during the correlation.
    eTExploreUpdateUsers = Sets/refreshes the global user attributes using account attribute values.

     

     

     

    Cheers,

     

    A.



  • 2.  Re: Use Powershell to call IM TEWS (SOAP)

    Posted 06-14-2016 10:27 AM

    Thanks Alan!

     

    Sagi



  • 3.  Re: Use Powershell to call IM TEWS (SOAP)

     
    Posted 10-15-2018 06:55 AM

    Hi Alan

     

    Is step 5 strictly necessary?

    If the provisioning role that you assign to the user in step 6 includes the account template from step 5, then can I achieve the same result by just applying step 6 without doing step 5 beforehand?

     

    Pearse



  • 4.  Re: Use Powershell to call IM TEWS (SOAP)

    Posted 10-15-2018 12:06 PM

    Hi Pearse,

     

    For normal use with a sync operation, you are correct, you can skip step #5, and when you apply #6, when a PR is attached to a Global User (via IMPS GUI or etautil), then it will auto build the direct inclusion for the Account Template to the Endpoint Account.   

     

    However, this may kick off a sync operation to the managed endpoint.   

    -  If you deem the risk to be low, this is acceptable. 

    -  However, if there is concern that a possible quota value will change (from 0 (unlimited) to # (some number), that would impact a sub-population of the legacy users, you may wish to address this by separating out the transactions.

     

     

     

     

    NOTE:   In latest release of IM r14.x, I have noticed (using etatrans & IMPD DSA trace mode) that when building the inclusion from Account Template (AT) to the EA (endpoint account pointer object), that two (2) inclusion events are generated, one is the direct update to the EA account for eTPolicyDN attribute, and the other appears to start to write to the Inclusion Branch DSA, but it appears to be "thrown away", as if it is no longer needed on this branch.

     

    Therefore, we now have the option to use ldapmodify or dxmodify directly to the IMPS service (tcp 20389/20390) to update the GU:PR via eTRoleDN  or  EA:AT via eTPolicyDN  with the full DN of the object.

    - Use ldapmodify or dxmodify will greatly speed up this process of building the "direct" inclusion

              -  with the added benefit of requiring an immediate sync operation that would increase risk for the 100,000+ existing users to have their access updated at once during a go-live.

     

     

     

    Example:

     

     

    Modify the eTPolicyDN for an existing EA (endpoint account pointer object - previously created by the Explore operation)

     

    ldapmodify -h localhost -p 20389 -D 'cn=etaserver,dc=eta' -W -f ~/policy.ldif

    dn: eTADSAccountName=testuser999,eTADSContainerName=Users,eTADSDirectoryName=AD_HOSTNAME_HERE,eTNamespaceName=ActiveDirectory,dc=im
    changetype: modify
    replace: eTPolicyDN
    eTPolicyDN: eTADSPolicyName=test-policy,eTADSPolicyContainerName=Active Directory Policies,eTNamespaceName=CommonObjects,dc=im

     

     

    Modify the eTPolicyDN with an ADD for the multi-value field of eTPolicyDN for an existing EA

    Note: there are two (2) eTPolicyDN values for different Account Templates on the single EA object.


     ldapmodify -h localhost -p 20389 -D 'cn=etaserver,dc=eta' -w Password01 -f ./policy_add.ldif

    modifying entry "eTADSAccountName=testuser999,eTADSContainerName=Users,eTADSDirectoryName=AD_HOSTNAME_HERE,eTNamespaceName=ActiveDirectory,dc=im,dc=eta"

    imps@vapp0001 VAPP-14.1.0 (192.168.242.146):~/logs >
    imps@vapp0001 VAPP-14.1.0 (192.168.242.146):~/logs > ldapsearch -LLL -h localhost -p 20389 -D 'cn=etaserver,dc=eta' -w Password01 -b eTADSAccountName=testuser999,eTADSContainerName=Users,eTADSDirectoryName=AD_HOSTNAME_HERE,eTNamespaceName=ActiveDirectory,dc=im,dc=eta -s base eTPolicyDN


    dn: eTADSAccountName=testuser999,eTADSContainerName=Users,eTADSDirectoryName=A
    D_HOSTNAME_HERE,eTNamespaceName=ActiveDirectory,dc=im,dc=eta
    eTPolicyDN: eTADSPolicyName=another-test-policy,eTADSPolicyContainerName=Activ
    e Directory Policies,eTNamespaceName=CommonObjects,dc=im
    eTPolicyDN: eTADSPolicyName=test-policy,eTADSPolicyContainerName=Active Direct
    ory Policies,eTNamespaceName=CommonObjects,dc=im

     

     

     


     ldapmodify -h localhost -p 20389 -D 'cn=etaserver,dc=eta' -w Password01 -f ./policy_mod.ldif
    modifying entry "eTADSAccountName=testuser999,eTADSContainerName=Users,eTADSDirectoryName=AD_HOSTNAME_HERE,eTNamespaceName=ActiveDirectory,dc=im,dc=eta"

     

     

     

     

    Use ldapsearch (or dxsearch) to view the eTPolicyDN value (before & after updates):

     

    ldapsearch -LLL -h localhost -p 20389 -D 'cn=etaserver,dc=eta' -w Password01 -b eTADSAccountName=testuser999,eTADSContainerName=Users,eTADSDirectoryName=AD_HOSTNAME_HERE,eTNamespaceName=ActiveDirectory,dc=im,dc=eta -s base eTPolicyDN


    dn: eTADSAccountName=testuser999,eTADSContainerName=Users,eTADSDirectoryName=A
    D_HOSTNAME_HERE,eTNamespaceName=ActiveDirectory,dc=im,dc=eta
    eTPolicyDN: eTADSPolicyName=test-policy,eTADSPolicyContainerName=Active Direct
    ory Policies,eTNamespaceName=CommonObjects,dc=im

     

     

     

     

     

     

    imps@vapp0001 VAPP-14.1.0 (192.168.242.146):~/logs > cat policy_add.ldif
    dn: eTADSAccountName=testuser999,eTADSContainerName=Users,eTADSDirectoryName=AD_HOSTNAME_HERE,eTNamespaceName=ActiveDirectory,dc=im,dc=eta
    changetype: modify
    add: eTPolicyDN
    eTPolicyDN: eTADSPolicyName=test-policy,eTADSPolicyContainerName=Active Directory Policies,eTNamespaceName=CommonObjects,dc=im

     

     

     

    imps@vapp0001 VAPP-14.1.0 (192.168.242.146):~/logs > cat policy_remove.ldif
    dn: eTADSAccountName=testuser999,eTADSContainerName=Users,eTADSDirectoryName=AD_HOSTNAME_HERE,eTNamespaceName=ActiveDirectory,dc=im,dc=eta
    changetype: modify
    delete: eTPolicyDN
    eTPolicyDN: eTADSPolicyName=test-policy,eTADSPolicyContainerName=Active Directory Policies,eTNamespaceName=CommonObjects,dc=im

     

     

     

    imps@vapp0001 VAPP-14.1.0 (192.168.242.146):~/logs > cat policy_mod.ldif
    dn: eTADSAccountName=testuser999,eTADSContainerName=Users,eTADSDirectoryName=AD_HOSTNAME_HERE,eTNamespaceName=ActiveDirectory,dc=im,dc=eta
    changetype: modify
    replace: eTPolicyDN
    eTPolicyDN: eTADSPolicyName=test-policy,eTADSPolicyContainerName=Active Directory Policies,eTNamespaceName=CommonObjects,dc=im

     

     

     

     

    Cheers,

     

    Alan



  • 5.  Re: Use Powershell to call IM TEWS (SOAP)

    Posted 01-02-2019 12:35 PM

    Thanks Alan for sharing. I was looking for an example PS script to make a TEWS call for a while now!

     

    As an FYI, if you guys try to test this against an environment with a self-signed certificate (like our standard demo environment), you will get a connection-closed error 'Could not establish trust relationship for the SSL/TLS secure channel'. 

     

    To get around the trust relationship issue, insert the following piece of code just before your Invoke-WebRequest call

     


    ### Without this code, script will fail to establish trust relationship for the SSL/TLS secure channel ###
    ### This is a problem that is usually encountered with self-signed certificates and the script will close the connection ###
    ### Begin Ignore Cert Validation code ###
    if (-not ([System.Management.Automation.PSTypeName]'ServerCertificateValidationCallback').Type)
    {
    $certCallback = @"
          using System;
          using System.Net;
          using System.Net.Security;
          using System.Security.Cryptography.X509Certificates;
          public class ServerCertificateValidationCallback
          {
             public static void Ignore()
             {
                   if(ServicePointManager.ServerCertificateValidationCallback ==null)
                   {
                         ServicePointManager.ServerCertificateValidationCallback +=
                         delegate
                         (
                               Object obj,
                               X509Certificate certificate,
                               X509Chain chain,
                               SslPolicyErrors errors
                         )
                   {
                         return true;
                   };
                }
             }
          }   
    "@
    Add-Type $certCallback
    }
    [ServerCertificateValidationCallback]::Ignore()

     

    ### End Cert Validation Ignore code