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

External User Store Integration (Platform versions before 8.2.0)

Note: The information on this page refers to Platform versions before 8.2.0. If you are using Platform version 8.2.0 or later, see the Identity Federation page.

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 (typically but not limited to an enterprise directory service such as Active Directory), the Platform can be configured to use that external User repository in place of its internal User Store. Also see the Active Directory set-up guides to use it with your Platform.

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 plugin is used by the Platform Authentication Service 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 ACP 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.

*It is important to 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, we recommend that the Platform Operations team be 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: Changing the Tenant Admin can only be performed in the SOC or Account Portal. Any changes to the objects that define the Tenant Admin role in the External User Store will be ignored by the Platform).

Configuring the Platform to Use an External User Store

Since the plugin will specify exactly how the Platform will communicate with your specific User Store instance, the solution that you upload to the Platform needs to specifically be created and customized for your Organization's use case.  For assistance with creating an External User Store plugin, please contact Apprenda Support at support@apprenda.com.

Before an External User Store can be configured, Identity Federation must be enabled for the Platform; this feature would have been enabled during the Platform install process.  Assuming that Identity Federation is enabled, from the Platform's System Operations Center (SOC), click on Configuration in the top menu, and then choose User Store from the resulting options.

Once you have created an External User Store plugin, you can upload the plugin from this page:

Click the Browse button, and locate your plugin in the file directory.   Once the plugin has been chosen, you can click the Test Connection button to confirm that the plugin allows the Apprenda 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 Identity Federation section:

Identity Federation should be enabled on the Platform, but it still needs to be configured to work with your Secure Token Service.  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; please provide your STS admin with the URL listed in the box on this screen.

Next, using the Map Identity Claims section, the Apprenda 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, and the pulldown selection to the right of the Claim (listed under Mapping) can be used to match that Claim with the corresponding External User Store attribute. Please note that you must map the correct attribute to the Platform User Account, as this is the information Apprenda 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 should 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

The following Platform Registry Settings can be configured by the Platform Operator 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)