Understanding Connection & Credential Alias

[Jake Gillespie]

Before I get into the magic of Connection & Credential Alias, let me talk a bit about (what I call) the legacy equivalent. Way back in 2014, I was tasked with building an outbound integration with a SOAP endpoint. So I created a SOAP Message and SOAP Message Function record similar to the one below.

While there were a couple of authentication options available, I was using Basic Auth which was common at the time. Note that I had to select my "Basic auth profile" as a direct reference on the SOAP Message Function record. While this worked great in the Development instance, it became a problem when I deployed the integration into another instance. Why? Because the SOAP Message Function record was captured into my Update Set and then deployed as-is, along with my Basic auth profile containing my credentials. This goes against security best practices because each environment (e.g. ServiceNow Instance) should use a different set of credentials. It was also a problem because the SOAP endpoint URL was hardcoded into this SOAP Message Function too.

Now I hear you saying "just update it with a manual post-deployment step". Ok, sure, we could do that. But what happens when the next clone from Production down to non-Production instances occurs? The default clone configuration would include this record, meaning our "Production" endpoint URL and credentials would now be in the non-Production instance(s), thus defeating the purpose of having separate credentials per environment in the first place! You can see where I'm going with this. I'll fast forward a little. I (of course) did not build the solution this way. I opted for a combination of System Properties and look-up script to override the endpoint URL and Basic auth credential values at the time of execution. This was a common practice at the time, albeit cumbersome and error-prone to maintain, let alone time-consuming to build. I should also mention that these issues were not exclusive to the SOAP Message configuration, they also existed for the legacy REST Message configuration as well.

Now that I've painted that grim picture, let's move on to greener pastures. Let's talk about what makes up a Connection & Credential Alias configuration. At its core, it is made up of 3 components: The Alias record, The Connection record, and (while optional) a Credential record. In comparison to the issues I described earlier regarding the legacy integration configuration, only the Alias record is captured into an Update Set (or Application Repository etc.) and is deployed as such. The Connection record is not captured, nor is it included in clones, as it is expected that each ServiceNow Instance will connect to a different endpoint URL. The same goes for the Credential record which is directly referenced by the Connection record. This architecture solves the environment management issue from earlier. Great!

So, how and where is this used I hear you ask? Well, it is natively used in Flow Designer, or Integration Hub to be more precise. Integration Hub Spokes will often contain Flow Actions where a (SOAP/REST/PowerShell/SSH etc.) Step references an Alias. This could be hardcoded or passed into the Flow Action as an Input. The same goes for custom integrations. From here, the Step will look up the Active Connection (and Credential) for that Alias at the time of execution and use those details. This is necessary because the Connection is cleverly defined as a Related Record against the Alias (as shown above). Not a direct reference (as we saw with the legacy configuration). It is possible to define more than one Connection against the same Alias, but it's more common to use a single Active Connection at a time. This allows Developers or System Administrators to easily repoint their integration from one endpoint to another if required. For example, you might first build the integration against a Development endpoint but then repoint it to a SIT endpoint for more in-depth testing.

There are more features I could talk about, but this article is already longer than I anticipated. Stay tuned for the next article!

[Mahesh_Krishnan]

Thank you for the informative write-up Jake! Now you got me thinking on my need to potentially refactor my OAuth process although I am not sure if you can use your approach for OAuth-based rest integrations. Can you?

[Jake Gillespie]

Hi @Mahesh_Krishnan,

Thanks for your comment. If you want to use an OAuth2.0 Credential with your Outbound REST Connection, you just need to configure the Application Registry first. I generally create an Application Registry in each instance rather than creating them all in Development and then deploying them through the environments. This is because the Application Registry contains the Client Secret which is a Password2 field type which is kind of like a credential for the OAuth2.0 token request. Not to mention the Token URL will likely be different for each environment. Application Registries are preserved during clones by default, just like the OAuth2.0 Credential records. I hope that helps!

[akash_mohne]

Hi @Jake Gillespie , 

It was great article which answers why moved to Alias. I  want to understand the purpose of child alias in the parent alias ?

[PriyaRanji]

@Jake Gillespie Hello Jake,

Thanks much for the detailed info.

Thanks,

Priyanka R

[AijaRe]

@Jake Gillespie Thank you for the explanation, very helpful!

If possible, could you clarify how this part is used when using several instances "only the Alias record is captured into an Update Set (or Application Repository etc.) and is deployed as such. The Connection record is not captured, nor is it included in clones, as it is expected that each ServiceNow Instance will connect to a different endpoint URL. The same goes for the Credential record which is directly referenced by the Connection record"

What would be the best practice when different endpoints/credentials are used in different instances (e.g., Dev, Test and Prod)? Should we deploy only the Alias record, and create Connection and Credential record manually in each instance? Or should we remove the credential passwords and force Connection and Credential records to the Update Set, and then after deployment activate the corresponding Connection and add password manually?
Thank you!

[JakeG]

Hi @AijaRe, because the Alias record is automatically captured to the Update Set it will (and should) be deployed to all environments as-is. Keep in mind it will be directly referenced by Flow Actions which would also be deployed. You do need a manual deployment activity to create the Connection and Credential records in each environment. This aligns with best practices for two reasons:

1. Each environment should use different credentials for better security.
2. Each environment should ideally connect to a unique endpoint to avoid security and/or data conflicts (e.g. Dev -> Dev, Test -> Test, Production -> Production).

A caveat on point 2 is if you are connecting to a single source of truth to pull data into ServiceNow (like user provisioning). In that case you'd end up with the same Connection and Credential values in each environment. However, the Credential record should still be created manually in (as opposed to migrated to) each environment given that the encryption keys for each environment almost certainly likely different (this depends on the KMF configuration). If they are different, migrating the Credential record would result in the target system being unable to use it, as the target environment cannot decrypt the password2 value in the Credential record (e.g. Basic Auth, API Key, etc). OAuth2 Credentials are a bit different as the Credential record doesn't store the token value, although the same principle of password2 encryption applies to the Client Secret field in the Application Registry record.