How to Configure a SuccessFactors Extension Application the Easy Way

How to Configure a SuccessFactors Extension Application the Easy Way

Suppose you have a SuccessFactors extension application you want to make available for customers. How would you go about that? Until recently, you would have had a single option – to go through a number of cumbersome manual configuration steps. Now, however, there’s another option. You can install and configure a SuccessFactors extension application in no more than 5 minutes with the help of a few SAP HANA Cloud Platform SDK commands.

Prerequisites

• You have an SAP HANA Cloud Platform account that has been onboarded with the SAP HANA Cloud Platform Extension Package for SuccessFactors.
• You have downloaded the latest SAP HANA Cloud Platform SDK

The information in this article is subject to change. The SAP HANA Cloud Platform console client commands used in the examples are still a beta feature undergoing continuous improvements so it is possible that they change somehow in the future. If you notice a behavior significantly different from that described below, please consult the official SAP HANA Cloud documentation.

Preparation

1. Deploy and Start the Extension Application

In order to install and configure the extension application you must first have an extension application deployed in your extension account (and it should be a java application since – as you will see in the limitation section at the end – the HTML5 scenario is still not entirely supported). You can deploy it from the SAP HANA Cloud Cockpit or with the help of the console client.

2. Enable Betа Features for your Account

It is possible that by the time you are reading this article, the commands mentioned below are no longer beta and it is not required that the beta features of the extension account are enabled. You can refer to the official documentation to check if that is so.

You can enable the beta features for any account from the SAP HANA Cloud Platform cockpit. Just go to the Account Details view by choosing the edit icon of the account.

For more information on how to enable the beta features, please refer to the official documentation.

Procedure

1. Enable Application Access

Extension applications – or indeed any application deployed in an extension account – authenticate users against the SuccessFactors instance linked to the account. When a user requests access to an extension application, they will be forwarded to the SuccessFactors login page where they can enter their credentials. In accordance with the SAML 2.0 specification, after successful login the identity provider (SuccessFactors) is expected to redirect the user back to the assertion consumer service, namely the extension application. There is a problem here, however. SuccessFactors differentiates between an authorized assertion consumer service and unauthorized (or unknown) assertion consumer service. Although the extension application trusts SuccessFactors to verify the user’s credentials, SuccessFactors does not trust the extension application as an assertion consumer service inherently. And because SuccessFactors does not trust the extension application, it will not redirect the authenticated user to this dubious source (it will indeed, not do this for any unauthorized assertion consumer service). The result is that, after entering their credentials, the user sees a blank page.

You have to register the extension application as an authorized assertion consumer service in SuccessFactors in order to have the system trust the application enough to redirect users back to it after login.

This can be done easily with the help of the SAP HANA Cloud Platform command ‘hcmcloud-enable-application-access’:

$ neo hcmcloud-enable-application-access –application myexampleapp –application-type java –account myextensionaccount –user ***** –host hana.ondemand.com

Enabling application access……………….

SuccessFactors IDP whitelist entry has been set for application ‘myexampleapp’ from account ‘myextensionaccount’:

Application Main URL       : https://myexampleapp.hana.ondemand.com/

Service Provider Audience URL     : https://authn.hana.ondemand.com/saml2/sp/slo/account/account

Service Provider Logout URL : https://hana.ondemand.com/account

The result of this command can be seen in the SuccessFactors Provisioning:

Now the extension application can be accessed without problems as SuccessFactors will redirect the request back to the application after successful authentication.

2. Configure Application Connectivity to SuccessFactors

The second step of the installation is the enablement of connectivity to SuccessFactors. Any productive SuccessFactors extension application is going to consume at least one of the SuccessFactors APIs in order to provide its functionality. The SuccessFactors OData API provides OAuth 2.0 authentication, which requires a registered OAuth client and a valid token. In order to consume the SuccessFactors OData APIs from an application running on the SAP HANA Cloud Platform, it is required to register an OAuth client in SuccessFactors and an OAuth 2.0 destination in HCP. Configuring that manually means going back and forth between the two systems. Luckily, the SAP HANA Cloud Platform command ‘hcmcloud-create-connection’ makes things a lot easier:

$ neo hcmcloud-create-connection –application myexampleapp –account myextensionaccount –user ***** –host hana.ondemand.com

Connection ‘sap_hcmcloud_core_odata’ to SuccessFactors has been created for application ‘myexampleapp’.

Created OAuth client with name HCP_EXT_SERVICE.

Created destination with name ‘sap_hcmcloud_core_odata’.

The newly created destination can be seen in the SAP HANA Cloud Cockpit:

Destinations in the SAP HANA Cloud Platform are consumed programmatically. The extension application must be written in a way that enables it to consume the ‘sap_hcmcloud_core_odata’ destination in order to take advantage of the connectivity to SuccessFactors that it provides. In the sample extension application used in the examples in this article, the destination is consumed in the following way (you can access the entire source code on GitHub):

  private DestinationConfiguration lookupDestinationConfiguration() throws IOException {
        ConnectivityConfiguration configuration = lookupConnectivityConfiguration();
 DestinationConfiguration destinationConfiguration = configuration.getConfiguration(this.destinationName);
        if (destinationConfiguration == null) {
            String errorMessage = String.format("Destination %s is not found. Make sure to have the destination configured.", this.destinationName);
            throw new IOException(errorMessage);
        }
        return destinationConfiguration;
    }
    private synchronized ConnectivityConfiguration lookupConnectivityConfiguration() throws IOException {
        try {
            if (this.localConnectivityConfiguration == null) {
                Context ctx = new InitialContext();
 this.localConnectivityConfiguration = (ConnectivityConfiguration) ctx.lookup("java:comp/env/connectivityConfiguration");
            }
            return this.localConnectivityConfiguration;
        } catch (NamingException e) {
            throw new IOException(e.getMessage(), e);
        }
    }

The ‘sap_hcmcloud_core_odata’ destination is also required in order to enable the SuccessFactors role provider to which the next section is devoted. You need to keep this in mind while coding your extension application.

3. Enable SuccessFactors Authorization

Almost every productive extension application has some security constraints based on roles – a functionality available to one type of users but not to another. In the web.xml of the sample application above there are two roles defined:

Let’s suppose that the extension application has a functionality that is visible only to users who have the ‘Analyzer’ role defined in the web.xml. The SuccessFactors user, sfexuser, logs into the application and a security check is performed immediately in order to determine what to show to this user. Since the application is running on the SAP HANA Cloud Platform, the default role provider (a module that retrieves the roles of a particular user) will be used to retrieve the roles of sfexuser. The SAP HANA Cloud Platform, however, is neither aware of a user named sfexuser nor has any notion of roles assigned to them. So the first step in enabling SuccessFactors authorization is to enable the SuccessFactors role provider for the extension application that is being installed. It will correctly retrieve all roles of a given SuccessFactors user directly from the SuccessFactors instance.

$neo hcmcloud-enable-role-provider –application myexampleapp –account myextensionaccount –user ***** –host hana.ondemand.com

SuccessFactors role provider has been enabled for application ‘myexampleapp’.

The ‘sap_hcmcloud_core_odata’ destination is required to enable the SuccessFactors role proider. The command ‘hcmcloud-create-connection’ has to have been executed beforehand.

If the user sfexuser accesses the extension application now, their roles will be correctly retrieved from the SuccessFactors instance. There is one more issue, however. SuccessFactors is not aware of a role named ‘Analyzer’ which is defined in the web.xml of an application running on the SAP HANA Cloud Platform. If the authorization is to work at all, the security roles used by the extension application have to be available and properly assigned to groups in the SuccessFactors system itself.

You define the roles that will be imported in the SuccessFactors instance in a file called roles.json:

The roles.json file is then passed as an argument to the following command:

$ neo hcmcloud-import-roles –account myextensionaccount –user ***** –host hana.ondemand.com –location C:\Desktop\roles.json

The roles are now imported in the SuccessFactors instance and can be assigned to specific user groups.

Then assign the role to an appropriate group and save the changes.

Once the ‘Analyzer’ role is assigned to a group that the user sfexuser belongs to, sfexuser will be authorized correctly and will see the restricted functionality in the sample extension application.

4. (Optional) Registering an Extension Home Page Tile

The SAP HANA Cloud Platform Extension Package for SuccessFactors provides a way to integrate the extension application directly inside the Success Factors Employee Central home page:

The extension tile (though they can be multiple tiles) that will be registered in the SuccessFactors system is first defined in the following tiles.json file:

The name property is an internal identifier of the tile and will not appear in the EC home page. The path property is very important – it is a relative (not absolute) path to the tile content page, starting from the root path of the application. The size property is an integer from 1 to 3 denoting the size of the extension tile, from medium to extra-large respectively. The padding property is a Boolean value that is either true or false that indicates whether the tile should have padding around it or not. The roles property is, naturally, a list of roles in SuccessFactors. In order to see the extension tile a user is required to have at least one of the listed roles. The metadata property is a nonempty list that contains the title of the extension tile in different locales. If there are several locales defined, the title that is shown for the home page tile will be chosen according to the locale of the user.

The path to the tiles.json file is passed as a parameter to the ‘hcmcloud-register-home-page-tiles’ command to register the tiles defined in the resource:

$neo hcmcloud-register-home-page-tiles –application myexampleapp –application-type java –account myextensionaccount –user ***** –host hana.ondemand.com –location C:\path\tiles.json

1 tile(s) were registered in SuccessFactors home page for ‘java’ application ‘myexampleapp‘.

The extension tile can point to an interactive page or an image, as you see fit.

Summary

We have now installed and configured our extension application. It can be easily accessed, it can consume the SuccessFactors OData APIs with the help of its ‘sap_hcmcloud_core_odata’ destination and has a role-based authorization mechanism that is tightly integrated with SuccessFactors. It is running on the SAP HANA Cloud Platform, enjoying its many advantages in performance, analytics and computing power. It can be accessed from the SuccessFactors Employee Central home page where it is seamlessly integrated with other home page tiles. And all this was achieved with just a few console client commands.

Known Limitations

At the moment the SuccessFactors role provider is not available for HTML5 applications. You also cannot configure connectivity to SuccessFactors for HTML5 applications. All of the other functionalities are supported for all types of applications.

Feedback

We are continuously working to improve the SAP HANA Cloud Platform SDK commands for SuccessFactors and value enormously any feedback we receive. If you like the commands and think they will make your work easier, please let us know in the comment section. If you think there is something we can do to improve them or that the documentation or the SDK help section is unclear, please also do not hesitate to leave a comment.