Windows AD integration

This describes changes to the 9.x release of the 1E Platform to support Windows AD integration, and it discusses associated functionality in the 1E PowerShell Toolkit to manage certificates.

About Windows AD integration

Earlier releases of the 1E Platform supported native NTLM authentication only. Subsequently, the platform was modified to delegate authentication to oAuth-compliant identity providers such as Microsoft Entra (Azure AD) and Okta.

However, customers who do not use external identity providers desire to upgrade to later versions of the on-premises version of the 1E Platform. Windows AD integration is a new feature for the 9.x platform which makes Windows AD look like an oAuth identity provider. This means that the platform itself and all associated tools, subsystems, and external systems (such as ServiceNow) continue to authenticate exactly as they previously did.

Configuring the platform for Windows AD integration

You configure the platform for Windows AD integration by setting values in the tenantconfig.json configuration file, just as for any other identity provider. Normally, you do not have to do this as the platform installer will take care of this for you.

A platform instance configured for Windows AD integration can subsequently be reconfigured to use an external identity provider such as Entra without requiring reinstallation. Conversely, a platform instance already configured to use an external identity provider can be reconfigured to use Windows AD integration.

Note that you need to consider principals that are defined in Role-Based Access Control (RBAC) when reconfiguring identity providers. These principals may not map to principals within the current identity provider’s directory, depending on naming conventions. Refer to Principals.

The 1E PowerShell Toolkit provides extensive functionality for principal remapping. If you do migrate a platform instance away from Windows AD integration to an external identity provider, where principals are likely to be stored in UPN format (that is, user@domain.com), then you can use the functionality to automatically update the RBAC database information and remap existing principals. Refer to Remapping principal names during legacy platform migration.

You specify the identity provider type as Windows. An application id for the client assertion app is automatically provided by the installer. Normally, this is a GUID whose values are 1E1E1E…. This value will be used by external integrators such as ServiceNow when creating and signing JWTs to authenticate non-interactively. You do not specify a directory search app id as searches are managed internally by the platform in this configuration.

The actual value you define for the client assertion app id isn’t important. It does not have to be unique per tenant, though it might be wise to set things up so that it is. As long as external integrators know what the app id is, they can create and sign a JWT to authenticate non-interactively.

Interactive authentication

The 1E PowerShell Toolkit will interactively authenticate with a 9.x platform instance configured for Windows AD integration exactly as it does currently, that is, you use the set-1eserver cmdlet and specify the server name. The authentication dialogue that you see is hosted by the platform, rather than an external identity provider.

MFA or Windows Hello are not supported. Only standard credentials (user account and password) are accepted.

Flows such as forgot password or unlock account are not supported. This must be handled externally to the 1E Platform within an organization, for example, via a support portal.

Non-interactive authentication

Similarly, non-interactive authentication using the 1E PowerShell Toolkit (or from external systems such as ServiceNow) works in exactly the same way as it does currently. You specify the destination server name, the application Id configured for the client assertion app id discussed above, and the subject or thumbprint of a certificate that can be used to sign the JWT.

The public key portion of this certificate must have been uploaded to the platform. Cmdlets to manage this process are included in the 1E PowerShell Toolkit. Refer to Windows AD cmdlets.

Certificate management for Windows AD integration

With an external identity provider, the public key of the JWT signing certificate is uploaded to the application specified for external integration. However, with Windows AD integration, the 1E Platform itself is acting as an identity provider, so you upload the certificate public key to the platform instead.

Principals

A principal in RBAC must be stored in the form domain\account. Even if a user logs on using the alternative account@domain.com format (that is, a UPN), Windows internally represents them as domain\account, and this is how they will be stored in the RBAC database and retrieved using the platform UI search. Just be aware of this so that if you use the 1E PowerShell Toolkit to manage principals, you enter them in the domain\account format.

Differences between Windows AD integration and external IdP configuration

There are some differences you should be aware of. These are discussed below.

No directory search application

You do not configure a directory search application id in tenantconfig.json for Windows AD integration. This is because directory searches are made directly by the platform using Windows APIs.

No configured redirect URL

Because there is no external identity provider, you do not configure a redirect URL. The platform handles the whole authentication process internally, so there is no need for this.

Metadata endpoint

The platform returns information from a metadata endpoint as per the OpenId standard but only a small subset of information is returned, sufficient for external integrators to parametrize a JWT for non-interactive authentication. For example:

Copy

1
2
3
4
5
6
{
    "authorization_endpoint": "https://tachyon.lab.local/Tachyon/api/Login",
    "token_endpoint": "https://tachyon.lab.local/Tachyon/api/NonStandardIdPProxy/ExchangeToken",
    "end_session_endpoint": "https://tachyon.lab.local/Tachyon/api/NonStandardIdPProxy/Logout/{tokenId}",
    "revocation_endpoint": ""
}

You request the metadata endpoint by calling the same platform endpoint that is used for external identity provider metadata retrieval, so there is no change to integration code.

Bearer tokens and identity provider APIs

You cannot use the 1E PowerShell Toolkit functionality associated with bearer tokens or calling identity provider APIs because the platform doesn’t emulate this functionality.