Prerequisites

• A delimited file is required to use this source.

• The first line of the file must be column headers.

S3 File Transport Prerequisites

In File Transport, you can use AWS S3 mode to access the file. Selecting AWS S3 shows Authentication Type, with two choices: IAM User and IAM Role. The IAM user or the assumed IAM role must have the following permissions on the target bucket and objects:

Without these permissions, the connector receives a 403 Forbidden error from S3. AWS returns 403 for both invalid credentials and insufficient permissions. Ensure your credentials are valid and have the required access.

Required S3 Permissions

The IAM principal, either the IAM user or the assumed IAM role, must have at least the following S3 actions:

IAM Role Authentication

With IAM Role, a source can read from S3 without storing a long-lived access key and secret. The virtual appliance assumes an IAM role through AWS STS, using its EC2 instance profile as the base identity.

IAM Role authentication requires all of the following. IAM User authentication is unaffected.

• The virtual appliance runs on an AWS EC2 instance. This method is unavailable for virtual appliances deployed elsewhere (VMware, Hyper-V, Azure, on-premises).

• An IAM instance profile is attached to that EC2 instance.

• If the instance uses IMDSv2, its http-put-response-hop-limit is set to 2 or higher. The default of 1 prevents the connector's container from reaching the instance metadata service.

• The instance profile role is permitted to call sts:AssumeRole on the target role.

• The target role's trust policy allows the instance profile role.

Same-Account Access

Use when the S3 bucket is in the same AWS account as the virtual appliance.

1. Create an IAM role in that account, for example S3ReaderRole, with a permissions policy granting s3:GetObject on arn:aws:s3:::<bucket>/*. Granting s3:ListBucket on arn:aws:s3:::<bucket> as well is optional and produces clearer errors when a connection test fails.

2. Set the role's trust policy to allow the virtual appliance's instance profile role:

   Copy

   {
     "Version": "2012-10-17",
     "Statement": [{
       "Effect": "Allow",
       "Principal": { "AWS": "arn:aws:iam::<account-id>:role/<va-instance-profile-role>" },
       "Action": "sts:AssumeRole"
     }]
   }

3. Attach a policy to the virtual appliance's instance profile role allowing sts:AssumeRole on arn:aws:iam::<account-id>:role/S3ReaderRole.

4. In the source's Connection Settings, set File Transport to AWS S3, Authentication Type to IAM Role, and Role Name to S3ReaderRole. Leave Account ID blank.

5. Select Test Connection.

Note
Do not enter the virtual appliance's own instance profile role as the Role Name. A role cannot assume itself unless its trust policy explicitly names itself, and the connection test fails with an access-denied error.

Cross-Account Access

Use when the bucket is in a different AWS account (Account B) from the virtual appliance (Account A).

1. In Account B, create the role with the same S3 permissions as above.

2. In Account B, set its trust policy to allow Account A's instance profile role, adding the external ID condition if you use one:

   Copy

   {
     "Version": "2012-10-17",
     "Statement": [{
       "Effect": "Allow",
       "Principal": { "AWS": "arn:aws:iam::<account-a-id>:role/<va-instance-profile-role>" },
       "Action": "sts:AssumeRole",
       "Condition": { "StringEquals": { "sts:ExternalId": "<external-id>" } }
     }]
   }

3. In Account A, allow the instance profile role to call sts:AssumeRole on the Account B role ARN.

4. In the source, set Role Name to the Account B role, Account ID to Account B's 12-digit ID, and External ID if the trust policy requires one.

IAM Role Behavior

• Credential refresh - Sessions are renewed automatically before they expire, so aggregations longer than the session duration are unaffected.

• CloudTrail - Each aggregation appears in your CloudTrail under the session name, so bucket access is attributable to a specific source.

• GovCloud and China regions - The role ARN partition is derived from the configured S3 region, so us-gov-* and cn-* regions are supported without extra configuration.

SMB File Transport Prerequisites

In File Transport, you can use SMB mode to read the file from a Windows File Server share or a Samba share. The same source fields apply to both. SMB authenticates with Kerberos only, so a Windows server in a workgroup cannot be used - it has no key distribution center (KDC) and no domain service principal.

Complete the following requirements before you configure the source. Most connection failures are caused by one of these requirements being missed, and several of them cannot be diagnosed from Identity Security Cloud alone.

File Share

• The share must support SMB2 or SMB3. SMB1 is not supported.

• The share must be a disk share. An administrative or printer share such as IPC$ cannot be used.

• The share must accept Kerberos authentication. If the server accepts only NTLM, the connection fails. The connector does not fall back to NTLM.

• The account file must already exist on the share, at the path configured in the source's file settings. The connector reads the share, not a local path on the file server.

Windows File Server

Complete these requirements when the share is on Windows Server.

• The server must be a domain member or a domain controller. Joining or promoting the server to the domain is what enables Kerberos. Installing the Active Directory Domain Services role is not enough while the computer is still in a workgroup.

• Install the File Server role (FS-FileServer) if it is not already present, then create the folder and share it as a disk share.

• Create an Active Directory user as the service account, and enable the AES128 and AES256 Kerberos encryption types on the account. The password must not be expired and must not require a change at next sign-in.

• Grant the service account Read permission on both the share ACL and the NTFS ACL of the folder and the file.

• Confirm that a service principal of the form cifs/<fully-qualified-host-name> exists. On a domain-joined Windows host, Active Directory registers HOST/<fqdn> on the computer account and treats it as an alias for cifs/, so an additional service principal is usually not required. Verify with setspn -Q cifs/<fully-qualified-host-name>.

• On the domain controller, the Kdc service must be running. That service is Kerberos on Windows - there is no separate Kerberos Server role.

• Verify the share from a domain-joined Windows client with dir \\<fully-qualified-host-name>\<share>.

Samba File Server

Complete these requirements when the share is on Linux.

• The host must be an Active Directory member or a Samba Active Directory domain controller. Standalone Samba with local users authenticates with NTLM and cannot be used.

• The share must accept Kerberos. Verify from a Kerberos-capable client with smbclient //<host>/<share> --use-kerberos=required. The smbclient utility is not present on a virtual appliance.

Kerberos Realm and Service Account

• A service account must exist in the Kerberos realm, with read permission on the share and on the account file.

• The service account password must not be expired.

• The KDC must resolve a service principal of the form cifs/<fully-qualified-host-name> for the host of the share. On Active Directory and Samba Active Directory, the host's HOST/ service principal usually satisfies this because the KDC treats it as an alias for cifs/. Verify with kvno cifs/<fully-qualified-host-name> from a machine that holds a ticket for the realm.

• The clocks on the virtual appliance and the KDC must be within the realm's tolerance of each other, which is five minutes by default. Kerberos rejects authentication outside that window.

Virtual Appliance

• The virtual appliance must reach the file share on TCP port 445.

• The virtual appliance must reach the realm's KDC on port 88, over both TCP and UDP. For a Windows member file server, port 445 is the file server and port 88 is the domain controller, which are often different hosts.

• A Kerberos configuration file mapping the realm to its KDC must be placed on the virtual appliance. The connector checks for krb5.conf first, then falls back to krb5.config.

• The connector locates the file through the Kerberos Configuration Directory field in the source's Connection Settings. Enter the directory that contains the file, not the path of the file itself, for example /opt/sailpoint/ccg/lib/custom. A trailing / is optional. The file must be readable by the sailpoint user.

• If you leave Kerberos Configuration Directory blank, the connector searches /opt/sailpoint/ccg/lib/custom and /home/sailpoint/ccg in that order, then the default Java location.

• Restart the Cloud Connection Gateway (CCG) service after you place the Kerberos configuration file on the virtual appliance for the first time.

The following is a minimal Kerberos configuration file. For a Windows File Server, kdc is the fully qualified name of an Active Directory domain controller that serves the realm, and the realm is the DNS domain in uppercase.

[libdefaults]
    default_realm = EXAMPLE.COM
    udp_preference_limit = 1

[realms]
    EXAMPLE.COM = {
        kdc = kdc.example.com
    }

[domain_realm]
    .example.com = EXAMPLE.COM
    example.com = EXAMPLE.COM

Caution
udp_preference_limit = 1 is required. A Kerberos service ticket for a Windows or Samba file share carries a privilege attribute certificate (PAC) that is usually too large for a UDP datagram, and the connector cannot process the KDC's request to retry over TCP. This setting makes Kerberos use TCP from the start. Omitting it is the most common cause of a failed SMB connection, on Active Directory as well as Samba.

Name Resolution

• The virtual appliance must resolve the host name of the share both forward and in reverse. The service principal is built from the canonical name returned by the reverse lookup, so if reverse resolution returns a different name, or none, the KDC rejects the request. Verify both directions from the virtual appliance with getent hosts <fully-qualified-host-name> and getent hosts <ip-address>. Both must return the same fully qualified name.

• Configure the source with the fully qualified host name, not an IP address. An IP address produces a service principal that the KDC does not recognize.

• If the realm is not in the DNS that the virtual appliance already uses, add a host entry in the hosts.yaml file on the virtual appliance instead of pointing the appliance's resolver at the domain controller. One malformed line disables every entry in the file. For more information, refer to Configuring Virtual Appliances.

Identity Security Cloud File Upload Utility

The Identity Security Cloud File Upload Utility provides a way for you to upload files to the cloud automatically.

You may use the Identity Security Cloud File Upload Utility with the Delimited File source. For more information about downloading and using the Identity Security Cloud File Upload Utility, refer to Identity Security Cloud File Upload Utility.

Best Practice
For best results, delimited files should not exceed 500 MB.