This is documentation for Apprenda 7 and 8.
Documentation for newer version is available at https://new.docs.apprenda.com.

Identity Federation (Platform version 8.2.0 and later)

As of Platform version 8.2.0, the Apprenda Cloud Platform provides a pluggable way to integrate with Identity and Access Management systems within your enterprise. By default, 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 that setup 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 and provides the step by step instructions on how to integrate the components with your enterprise's system that enables Single Sign-On and store identities, credentials, and attribute objects.

The information on this page is for Platform version 8.2.0 and later. If you are using Identity Federation on Platform versions before 8.2.0, see the External User Store page.

Federation Gateway

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

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 (https://www.identityserver.com), 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 and access control mechanisms as a record of User Identities and attributes for Platform access. However, if your Organization wants to use an already-established User repository to enable Platform Identity and Authorization, you can configure the Platform to use that external User repository instead by uploading a plugin known as the External User Store plugin.

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 (i.e. Platform Authorization for Developers). 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.

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 Organization's IdP. The plugin is a packaged archive that includes a JSON-based configuration file with implementations for either WS-Fed or SAML2. See more about building a FSP Plugin and defining your IdP configuration.

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.

Upload FSP Plugin

Before uploading your FSP plugin, make sure there is a trust relationship with the external IdP and the Platform Federation Gateway. The Federation Gateway for a Platform is located at https://[PlatformURL]/authentication/ where PlatformURL is the URL for the Platform.

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.

Test and Enable the Plugin

Once your plugin is uploaded, test the connection to the plugin before you enable it plugin by clicking Test Federation. Contact you support representative if you experience problems connecting to the plugin.

After successfully testing the connection, click Enable Plugin. The Platform will begin to use your FSP plugin immediately.

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. Make sure there is a trust relationship with the external IdP and the Platform Federation Gateway. The Federation Gateway for a Platform is located at https://[PlatformURL]/authentication/ where PlatformURL is the URL for the Platform
  2. Use the Test Harness application, described in the next section, to test the new FSP plugin and make sure that everything is working as expected. This step is not required, but strongly recommended
  3. Change the AllowIdentityFederation Platform Registry setting to False
  4. Upload a Federation Service Provider plugin through the SOC
  5. Add the Apprenda.Authentication.IssuerUrl  to be https://[PlatformURL]/authentication/wsfed where PlatformURL is the URL of the Platform
  6. 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 through its own JSON configuration file. Contact your support representative about getting the Test Harness application for testing your Platform.

To use the Test Harness application, you must update the activePlugin setting in the Web.config file in the root interface of the Test Harness archive to use the correct protocol of your IdP.

<add key="activePlugin" value="[wsfed/saml]" />

Testing using JSON Configuration File

To test your FSP plugin uses the correct endpoints, metadata, and keys for integrating with an external IdP, you can package the JSON configuration file you plan to use for a FSP Plugin with your Test Harness application. Once the configuration is correct, you can the package that JSON file with your FSP plugin.

When using the Test Harness application, you should run your web browser in a clean cookie state, like Incognito Mode for Google Chrome, and make sure there is a trust relationship with the IdP and your Test Harness application. The URL for a Published Test Harness application is https:/[CloudURI]/[appalias], where CloudURI is the Platform URL.

Deploying and Using the Test Harness Application

Deploy the application to the Platform and set the User Access Model to Anyone (this is set by default), and promote the application to Sandbox or Published. Note that the alias in Sandbox is different that in Published.

Testing your IdP

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

In the application, click Sign On. If you are not redirected to the IdP's authentication page, there is a problem with your configuration and you must adjust the configuration in your provided JSON file or your IdP. If you make any corrections to your JSON configuration file, patch your Test Harness application with the new application archive.

If you are able to access your IdP's login page, you can further test your FSP plugin by setting the User Access Model to Authentication or Authorization to see the claims that are passed from your IdP to the Platform. To see these claims, click View Claims in the Test Harness Application.

Note: You can only change an application's User Access Model when all versions of an application are in the Definition stage. If you want to test the claims being passed between your plugin and IdP, you must demote the application, change the User Access Model to Authentication or Authorization if the application is in Sandbox stage, or, if the application is in Published, add a new Test Harness application, change the User Access Model to Authentication or Authorization, and promote the application to Sandbox or Publish.

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 support@apprenda.com.

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.

Platform Registry Settings for Federation Gateway and User Stores

Federation Gateway Settings

Note that the following settings are not visible through the SOC. See more on managing this type of Registry Setting.

Name Explanation Values

Apprenda.Authentication.CookieEncryptionThumbprint

(valid as of Platform version 8.1.0)

Thumbprint of the certificate used to encrypt cookies. String

Apprenda.Authentication.EncodeCookies

(valid as of Platform version 8.1.0)

Determines if the Platform should encode cookies to identify the thumbprint of the certificate used to encrypt the cookie.

True (default), False

Apprenda.Authentication.FederationMetadataUrl

(valid in Platform version 8.1.0 and 8.2.0)

URL to the Platform's federation metadata String

Apprenda.Authentication.IssuerUrl

(valid in Platform version 8.1.0and 8.2.0)

The URL to the WS-Federation authentication provider for the Platform String

Apprenda.Authentication.SigningCertificateThumbprints

(valid as of Platform version 8.1.0)

Comma separated list of certificate thumbprints. The Platform uses the first thumbprint the authentication site successfully binds for signing claims. String

 

External User Store Settings

Name Explanation Values
Platform.ExternalUserStoreRoleAssignment Configures whether or not Roles assigned to individual Users are updated to match Role assignments in an External User Store (EUS).

Ignore: Role assignments for Users on the Platform are not updated to match Role assignments in the EUS.

Additive: Role assignments for Users on the Platform are updated only when Role assignments are added for a given User in the EUS

Exact: Role assignments for Users on the Platform are updated when Role assignments are added or removed for a given User in the EUS

(values are case sensitive)

Platform.ExternalUserStoreRoleCreation

Configures whether or not the Roles associated with Tenants on the Platform are updated when new Roles are added in an External User Store (EUS).

This setting will take effect only if the value for the Platform.
ExternalUserStoreRoleAssignment settings is Additive or Exact

Ignore: Roles on the Platform are not updated to match Roles added in the EUS
Additive: Roles on the Platform are updated to match Roles added in the EUS

 (values are case sensitive)