External User Store Integration

By default, the Platform uses its own native User Store as a record of User credentials for Platform access. However, if your Organization wishes to use an already-established User repository, you can configure the Platform to use that external User repository in place of its internal User Store.

To use an External User Store, you must enable Identity Federation during installation and then upload a custom plugin to the Platform through the Configuration>User Store page in the SOC.

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. The Platform Authentication Service 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. 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.

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 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).

Configuring the Platform to Use an External User Store

Prerequisites

  • Identity Federation enabled on your Platform. This can be enabled during Platform installation.
  • A customized External User Store Plugin. Since the plugin will specify exactly how the Platform will communicate with your specific User Store instance, you need to create and customize a solution specifically for your Organization’s use case. For assistance with creating an External User Store plugin, please contact Apprenda Support at support@apprenda.com.

Add your Eternal User Store plugin through the Configure User Store section of the Configuration>User Store page in the SOC.

To add your plugin to the Platform, click browse under Upload a custom user store plugin and locate your plugin in the file directory.

After selecting 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 Apprenda Support for assistance with the plugin. If the connection is successful, continue down the page to the Configure Federation Service Provider to further configure your plugin’s behavior. If you are Platform versions before 8.2.0, this section is called Configure Identity Federation.

Identity Federation

On the Apprenda Cloud Platform a Federation Gateway is the ACP Authentication UI component that brokers trusts between applications and an Identity Provider (IdP). Applications can refer to both the Platform Portals (Develop Portal, Account Portal, and SOC) and guest applications that have been configured to used 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 most often 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.

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.

The Federation Service Provider Plugin

To configure Identity Federation on your Platform, you need to upload a The Federation Service Provider (FSP) 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 utilize and customize for your enterprise environments. Contact your customer representative for more details.

An example external IdP description:

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

}

Configure Identity Federation on Platform (Platform version 8.2.0 and later)

Before you can your Platform to utilize an external IdP/STS for Identity Federation, you must build an Federation Service Provider plugin that describes your external IdentityProvider.

To upload your FSP plugin, navigate to the Configuration>User Store page in the SOC.

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

After successfully testing the connection, click Enable Plugin.

Edit the DefaultHomeRealm Registry Setting to value used in the authenticationType value in the IDP plugin configuration. For eaxample, 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 FSP plugin through the SOC
  3. Update the Apprenda.Authenticaiton.IssueUrl and DefaultHomeRealm registry settings with the new information for your FSD plugin
    • Apprenda.Authenticaiton.IssueUrl:

    • DefaultHomeRealm:

  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.

Identity Federation Test Harness

In Platform version 8.2.0 and later, to help test your 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.

Configuring the Platform for Identity Federation (Platform versions before 8.2.0)

Your Platform should already have Identity Federation enabled on the Platform, but you still need to it configure it to work with your Secure Token Service. In the Configure Identity Federation section, enter the URL for your Secure Token Service metadata in the input field, and click Retrieve Metadata. The Platform will use this metadata to align itself with the Secure Token Service authentication process. 

Next, your Secure Token Service administrator will need to configure STS to trust Apprenda. Provide your STS admin with the URL listed in the box on this screen.

Next, using the Map Identity Claims section, the Platform needs to know how to map its User attributes to the User information catalogued in your External User Store:

Each Claim in the left list is an Apprenda User attribute. Use the the pulldown selection to the right of the Claim (listed under Mapping) to match that Claim with the corresponding External User Store attribute. Note that you must map the correct attribute to the Platform User Account, as this is the information the Platform uses to link its User identification to the correct STS User. Once you’ve mapped User attributes to your satisfaction, click the Update Mappings button to save the settings.

Finally, you can test your External User Store settings by opening a private browser session and navigating to the URL listed in the box under the Test Federation heading:

You will be prompted to log in with STS credentials, after which you will see a message confirming that your External User Store has been configured correctly.

Before you enable the External User Store configuration, you have the option (under the Additional Configuration heading) to allow Tenants to customize their individual Federation setups. Once your settings are complete, click the Enable Plugin button at the bottom of the screen to enable your External User Store plugin. All Users catalogued in your External User Store will (assuming they have the correct permissions assigned) be able to use their credentials to log in to the Apprenda Platform as well.

Platform Registry Settings that Affect External User Store Behavior

Use the following Platform Registry Settings to configure to specify how Roles and Role assignments for individual Users on the Platform sync up with Roles and Role assignments in an External User Store.

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)