Source Account Schema Best Practices

[#1]

Overview

Within IdentityNow’s connectivity platform, there are three general categories of connectors which can be leveraged to integrate with target applications: Dedicated Connectors, Standards-Based Connectors, and Generic Connectors. For all classes of connectors, implementers have wide latitude in which account attributes are included as part of the schema, which attributes have special designations for the account, and which are used as entitlements.

This document describes some best practices for how to select and appropriately configure source attributes based on the type of connector being implemented.

Schemas

Before delving into specific connector types and attributes, it is important to understand that SailPoint’s connectivity model supports two different kinds of attributes: account-level attributes and entitlement-level attributes. We organize these two classes into “schemas,” used to inform our products which object we are actually interacting with during a given connectivity task.

Account Schemas

The attributes selected within a source’s account schema drive what information is actually brought into IdentityNow. One can equate an account schema to a kind of “data filter.” This ensures that only the desired information (as defined by the account schema) is taken from that data flow and brought into the cloud, regardless of the information actually served up by the target application’s integration layer.

Because connectors reside on the Virtual Appliance within a customer’s network, or on the customer’s IdentityNow tenant directly via SaaS 2.0 connectivity, account schemas ensure that customer data elements excluded from the account schema never get saved to the SailPoint environment through our integration.

Account ID and Account Name

A very important concept to understand when it comes to account schemas is the nature of two very special attributes: Account ID and Account Name. Upon aggregation of accounts, IdentityNow will create a “basic” identity cube for every new user account that is seen, irrespective of whether that source is tied to an identity profile. This basic identity cube must have two attributes populated: Account ID and Account Name.

Account ID is used to identify a specific, unique account. Often it is used within the buildmap process to “compile” multiple response elements into a single account link. For example, if a database source sends multiple rows for a single user account - i.e., a separate entitlement being provided on each row - then the Account ID attribute is used to ensure that all rows which belong to the same user are in fact collected to that identity. Thus, Account ID should always be assigned to an attribute which is guaranteed to be unique across all users in the target system.

Account Name is not as straightforward as Account ID. Its name implies that this attribute should be mapped to an account attribute which contains the user’s display name or an otherwise human-friendly value. This is incorrect. Account Name designates the “name” of the account being aggregated, which becomes the internal name for that “basic” identity cube. It is always a best practice to ensure that Account Name is mapped to an attribute that is guaranteed to be unique, much like Account ID. This is because the IdentityNow system will automatically check to see if any other “basic” identity cubes have the same Account Name value during a given account aggregation if no other correlation rules for that source are satisfied. If a matching cube is found, the new account will be correlated to that object instead of creating a new “basic” identity cube. This often leads to unintended correlation, and in extreme cases, can result in a significant downgrade to the tenant’s performance if hundreds of accounts have the same value for Account Name.

Adding and Removing Attributes

By default, our dedicated connectors (Workday, Active Directory, ServiceNow, etc.) come with many attributes on the schema out-of-the-box. This is great for a ‘quick start’ and to view what data the customer has.

However, more often than not, the customer will be using undefined attributes they wish to aggregate. These will need adding to the schema.

On the flip side, many of the default attributes may not be required. These should be reviewed and risk assessed for best-practice security, specifically with data privacy and data protection in mind, given that account data is downloadable via the Admin UI.

Furthermore, the customer may have an internal contract agreement with a system that it will only read/write to a predefined set of attributes. This is often captured in an Interface Control Document (ICD).

One means of meeting that use case could be by restricting the Service Account permissions, but sometimes such customization to the permission set is not possible and the attributes need to be removed from the schema to ensure compliance. This is particularly applicable to systems which hold Personally Identifiable Information (PII) - such information is seldom necessary for identity governance, so if we have no need to aggregate or provision a given attribute, it should be considered for removal from the schema.

Entitlement Schemas

Whereas account schemas tell IdentityNow which account attributes are meaningful, entitlement schemas tell IdentityNow which account attributes denote access within the target application. Flagging an attribute in the account schema as an entitlement ensures that IdentityNow automatically adds new values discovered via aggregation to the entitlement catalog, which can then make those values requestable and revocable via provisioning and certifications, respectively.

The “schema” part of this configuration indicates which additional information about that entitlement attribute can be gleaned from the target system. For many applications, the entitlement itself has multiple attributes which can be helpful to know for governance. Attributes such as description, relationship to other entitlements, or even flags such as privileged or SOX-related, are all pieces of data that can embellish what IdentityNow knows about that access item.

For entitlement schemas, the key piece of information to keep in mind is that IdentityNow can support multiple entitlement schemas, but only one can be designated as the “group” schema attribute. This designation tells IdentityNow which attribute to look for when conducting an entitlement aggregation. All other entitlement attributes are only collected during account aggregations (and are added to the catalog of requestable objects as described above).

Dedicated Connectors

The most common integrations we see across our customer base are those that connect to popular applications: Active Directory, Workday, SuccessFactors, Azure Active Directory, ServiceNow, etc. Due to these systems' popularity, SailPoint’s engineering teams have created “dedicated” connectors that are meant to integrate cleanly and consistently with those platforms. Our engineering teams invest significant resources and time to ensure that the integrations are stable, supportable, and up-to-date with any changes that might be scheduled by the vendors who deliver those target applications.

Out of this effort, our teams have identified which attributes are most common, which are intended to always be unique identifiers, and which are intended to be the managed attributes (“group”-level entitlements) on those sources. This knowledge is captured within SailPoint’s out-of-the-box source configurations, and it is imperative that implementers do not modify these configurations away from the system defaults. For many applications, the engineering teams who build SailPoint’s connectors have coordinated with the IdentityNow product engineers to always build provisioning plans around these configurations, so changing those would detrimentally impact how the product behaves.

Account Attributes

For our dedicated connectors, the out-of-the-box account attributes should satisfy most customers' use cases. Certain attributes can be added, and certain others can be excluded, to meet customers' specific needs. At the bare minimum, the AccountID, AccountName and Managed Attribute (commonly referred to as the “group attribute”) selections should always remain intact. Some common examples of dedicated connectors and their core attribute defaults are:

• Active Directory

  • Account ID: distinguishedName

  • Account Name: sAMAccountName

  • Managed Attribute: memberOf

• Workday

  • Account ID: FILENUMBER

  • Account Name: FILENUMBER

• ServiceNow

  • Account ID: sys_id

  • Account Name: user_name

  • Managed Attribute: groups

• SuccessFactors

  • Account ID: PersonID

  • Account Name: FormalName

  • Managed Attribute: Groups

Entitlement Schemas and Attributes

For dedicated connectors, the out-of-the-box configurations for entitlement attributes and schemas are generally sufficient. Implementers may choose to bring in additional fields as entitlements but that is rarely needed, and they should never change the default group schema configurations away from what SailPoint provides by default.

Standards Based Connectors

SailPoint's standards-based connectors are, for the most part, implementations of a connectivity layer that follow a known design pattern. For example, the SCIM 1.1 and SCIM 2.0 connectors abide by the System for Cross-domain Identity Management standards agreed upon by the creators of those standards, but the actual connectivity layer is still comprised of generic RESTful calls via HTTP/S. Similarly, OpenLDAP is based off the Lightweight Directory Access Protocol and abides by certain standards, though it still communicates on basic TCP/UDP channels. In most cases, standards-based connectors support (and expect) a base set of attributes by default, but also allow for some extensibility to support more customized use cases.

Account Attributes

For standards-based connectors, the core schema attributes defined by the standard are automatically selected for implementers when onboarding that connector in IdentityNow. It is rarely necessary to deviate from these selections, and SailPoint’s recommendation is to not modify these attributes unless the implementer is fully aware of what those modifications mean. Some common examples of standards-based connectors and their core attribute defaults are:

• OpenLDAP

  • Account ID: dn

  • Account Name: cn

  • Managed Attribute: groups

• RACF

  • Account ID: USER_ID

  • Account Name: USER_ID

  • Managed Attribute: groups

• SCIM 2.0

  • Account ID: externalId

  • Account Name: userName

  • Managed Attribute: group

Important Note: For some standards-based connectors, such as SCIM, the standard offers automatic discovery of the account schema: the standard supports a call which will return the attributes and schemas which are supported by that specific application. Wherever possible, the self-discovery feature of a standards-based connector should be leveraged and the results left “as is.”

Entitlement Schemas and Attributes

Similar to dedicated connectors, the out-of-the-box configurations for entitlement attributes and schemas on standards-based connectors are generally sufficient. Implementers may choose to bring in additional fields as entitlements but that is rarely needed, and they should avoid changing the default group schema configurations away from what has been already provided by SailPoint or discovered via the target system’s self-describing features.

Generic Connectors

SailPoint's generic connectors are far and away the most flexible integration options when a dedicated connector does not yet exist, and when the target application does not support a publicly documented and adopted standard. These connectors leverage a common, “base-level” connectivity layer but leave the actual structure of messages up to the developers who are integrating with the system. The most common generic connectors at SailPoint are Web Services, JDBC and Delimited File. These connectors leverage RESTful APIs, Java-based database connections, and flat file structures, respectively, to send and receive data between IdentityNow and target applications.

Account Attributes

True to their name, generic connectors do not come with any out-of-the-box attributes. The expectation is that the implementer will know which attributes are available from the target system, and which will need to be aggregated into IdentityNow. Thus, implementers should be prepared to do some research against the target system to find out which attributes satisfy uniqueness, which denote access items, which are multi-valued, etc.

Entitlement Schemas and Attributes

Entitlement schemas for generic connectors also come out-of-the-box with no entitlement information. Similar to account attributes, the expectation is that the implementer will define these data elements for the connector and “teach” IdentityNow which operations correspond to which data models. The IdentityNow source configuration UI does provide an ability to create and manage entitlement schemas for generic connectors. While configuring these sources, implementers should reference our productized documentation to ensure that the integration yields the intended results.