Identity Federation (Platform version 8.2.0 and later)

As of Platform version 8.2.0 and later, the Apprenda Cloud Platform provides a pluggable way to integrate with Identity and Access Management systems within your enterprise. Out of the box, the Platform is configured to use its own internal source to store Identities and authenticate users, however, enterprises typically manage identities and access controls centrally through the use of directory services, Identity Providers (IdPs), and Security Token Services (STSs).

To utilize an enterprise’s off-Platform systems for Federated Identity and Access Management, Platform Operators can integrate it into a Platform using two components of the Platform Authentication Service: The Federation Gateway and the External User Store. This page explains the roles of these components as well as the step by step instructions to integrate the components with the systems that enable Single Sign-On and store identities, credentials, and attribute objects.

If you are using Identity Federation on Platform versions before 8.2.0, see the External User Store page.

Federation Gateway

For users to Authenticate to applications on the Platform using their Single Sign-On (SSO) credentials, Platform Operators need to configure the Federation Gateway, which is the ACP Authentication UI component that brokers trusts between applications and an IdP. Applications can refer to both the Platform Portals (Develop Portal, Account Portal, and SOC) and guest applications that have been configured to use Platform Authentication.

In a basic Platform configuration, the IdP is also represented by the ACP Authentication UI component. However, in most enterprise configurations, an IdentityProvider/Security Token Service (IdP/STS) is a third-party endpoint that holds information about user’s identities and issues cryptographically-protected claims tokens through a number of standard protocols (i.e. SAML, WS-Fed, and OIDC/OAuth2).

In the enterprise scenario, where a Platform is configured for Identity Federation, the Federation Gateway is powered by IdentityServer (, a framework and hostable component that allows implementing authentication and access control for web applications and APIs using standard protocols. In this scenario, the Federation Gateway acts as a Federation Service Provider.

Configuring the Federation Gateway to trust a third-party IdP/STS is done by uploading a Federation Service Provider plugin in the SOC.

Note: For High Availability, you can increase the number instances of the Federation Gateway in the SOC by scaling up the Authentication UI. This is recommended for production environments.

External User Store

By default, the Platform uses its own native User Store as a record of User credentials for Platform access. However, if your Organization wants to use an already-established User repository, you can configure the Platform to use that external User repository instead place of its internal User Store by uploading another plugin known as the External User Store plugin. Configuring the Platform to use an External User Store will allow your Organization to use a single repository of User credentials for all types of account access, for the Platform as well as for other Organization infrastructure.

The Platform Authentication Service component uses the plugin to query the User Store to confirm a user’s identity and how the user maps to a Tenant on Platform according to your Organization’s business rules. The plugin further enables role-based access control inside the Developer Portal by mapping user objects to Platform roles like the Tenant Admin as well as authenticating users to the Platform without using a browser (e.g. Apprenda Cloud Shell (ACS), Visual Studio Extension, and REST API).

Configuring Identity Federation through Plugins

To configure a Platform for Identity Federation, Platform Operators must upload both a Federation Service Provider and External User Store plugins in the SOC. Unlike in previous Platform versions, Identity Federation should be configured after the Platform is installed.

Federation Service Provider Plugin

For Platform Identity Federation, you need to upload a Federation Service Provider plugin that describes your external IdP. The plugin is a packaged archive that includes a JSON-based configuration file with implementations for both WS-Fed or SAML2.

Apprenda has pre-built implementations of this archive available for you to use and customize for your enterprise environments. Contact your support representative for more details.

An example external IdP description:

        "metadataAddress": "https://apps.apprenda.bxcr/idp/wsfed/metadata",
        "wtrealm": "$#ApprendaBaseAddress#$",
        "blackchannelTimeout": "00:01:00",
        "refreshOnIssuerKeyNotFound": true,
        "userTokenLifetime": true,
        "authenticationType": "https://apps.apprenda.bxcr/idp",
            "tokenEndpoint": "https://apps.apprenda.bxcr/idp/wsfed",
            "issue": "https://apps.apprenda.bxcr/idp"


Upload FSP Plugin

To upload your plugin, navigate to the Configuration>User Store page in the SOC. In the Configure Federation Service Provider section, click browse and select your plugin archive.

Once your plugin is uploaded, you must test the connection before you can enable the plugin. To test the connection, click Test Federation. Contact you support representative if you experience problems connecting to the plugin.

After successfully testing the connection, click Enable Plugin. This will take immediate affect on your Platform.

Configure Platform to use FSP Plugin

After uploading you FSP plugin, you must configure you Platform to use the new plugin by editing the DefaultHomeRealm Registry Setting to value used in the authenticationType value in the IDP plugin configuration.

For example, given the example IdP configuration above, the new value for DefaultHomeRealm should be https://apps.apprenda.bxcr/idp.

Note: To revert back to the Platform IdP, change the setting back to the default value: urn:SaaSGrid.

Migrating to new the Identity Federation Model

Platform version 8.2.0 introduces a new Identity Federation Model. If you are upgrading to Platform version 8.2.0 or later and wish to continue using Identity Federation on your Platform, you must migrate to the new Federation Model.

Note: Migrating to the new model requires that you disable login until the new Federation Model is configured. Its recommended that you notify all Platform users of the change and potential inaccessibility of their applications.

To migrate to the new federation model,

  1. Change the AllowIdentityFederation to False. Note: Login will not work after this change without choosing from the Ad FS home realm discovery page.
  2. Upload a Federation Service Provider plugin through the SOC
  3. Update the Apprenda.Authenticaiton.IssuerUrl and DefaultHomeRealm (your security policy domain) registry settings with the new information for your plugin
  4. Undeploy all instances of the Federation Service through the SOC

After the migration, nodes that were dedicated to running the legacy Federation Gateway powered by AD FS are no longer needed for that purpose.

Federation Service Provider Test Harness

To help test your FSD plugin and external IdP configuration on the Platform, Apprenda can provide you with a Test Harness application. This application validates that the Platform receives the required claims from the IdP. Contact your support representative about getting the Test Harness application for your testing Platform.

Deploying the Test Harness Application

Deploy the application to the Platform and set the User Access Model to “Authorized” (note that the default is set to “Anyone”), and promote the application to the Published stage.

Testing your IdP

Once the Test Harness application is in the Published stage, navigate to the application by launching from the Application page in the Developer Portal or the Application Details page in the SOC.

Log into the application with existing user credentials on the Platform. After log in, click View Claims to see the claims that are passed from the IdP to the Platform. Relevant to Registry Settings for Identity Federation

The User Store Plugin

To enable your Organization’s chosen User Store on the Platform, you will need to use a plugin configured specifically for that User Store. Note that changes to the structure of the User Store (e.g. changing the names of attributes and groups) can cause disruption to user access on the Apprenda Platform.

Once an External User Store (EUS) plugin is installed on the Platform, its recommended that the Platform Operations team are aware of planned configuration changes being made to the User Store that would impact how user objects are defined in the plugin so that a new plugin version can be installed to align with those changes (NOTE: You can only make changes to the Tenant Admin in the SOC or Account Portal. Any changes to the objects that define the Tenant Admin role in the External User Store are ignored by the Platform).

For the EUS plugin you need to create and customize a solution that will specify exactly how the Platform should communicate with your User Store instance. For assistance with creating an EUS plugin, contact your support representative at

Upload a EUS Plugin

From the Configuration>User Store page in the SOC, upload your EUS plugin through the Configure User Store. Click browse and locate your plugin in the file directory.

After uploading your plugin, use the Test Connection button to confirm that the plugin allows your Platform to connect to your User Store. If the connection fails, contact your support representative for assistance with the plugin.