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.


/wp-content/uploads/2016/05/enable_beta_features_overview_964872.png

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 loioabfe4243d43d42a2a59eb64733ac7a75_LowRes.pngof the account.

/wp-content/uploads/2016/05/account_details_964895.png

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:

/wp-content/uploads/2016/05/acs_view_964896.png

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:

/wp-content/uploads/2016/05/destination_964897.png

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:

/wp-content/uploads/2016/05/webxml_964898.png

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:

/wp-content/uploads/2016/05/rolesjson_964899.png

In the example, the list of permissions is empty, because the roles that will be imported are not associated with any specific SuccessFactors permissions. If that is not so in the case of your extension application, please refer to the official documentation.


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.


/wp-content/uploads/2016/05/add_roles_964900.png

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.

It is a good idea to give your custom security roles unique names in order to make sure they don’t collide with other roles in the SuccessFactors system.

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:

/wp-content/uploads/2016/05/homepahe_964901.png

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:

Untitled.png

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

/wp-content/uploads/2016/05/homepage2_964903.png

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.

To report this post you need to login first.

13 Comments

You must be Logged on to comment or reply to a post.

  1. Agata Nowak-Mizerka

    Dear Tanya,

    It’s very helpful post, but i would like to double check if i understand it correctly.

    Suppose that application is deployeed and started on Hana Cloud portal, I did all steps that you described and aplication is avaiable for successfactors users.

    User log in to successfactors and uses this application. Does this user have to authorize to HCP?

    Best Regards,

    A.

    (0) 
    1. Tanya Hristova Post author

      Hi Agata,

      The user will be authenticated and authorized by the HCP security layer as well but that will happen automatically and seamlessly – the user won’t see any HCP login screens or anything else.

      The extension account uses the SuccessFactors IdP so the user, having already logged into SuccessFactors, is automatically authenticated in the HCP application running in that extension account as well. And, since the HCP application uses the SuccessFactors role provider, authorization is also performed using his or her SF roles and permissions.

      Best regards,

      Tanya

      (0) 
      1. Agata Nowak-Mizerka

        Tanya,

        Thanks for your quick reply.

        Does it mean that every user who wants to use this application need to have his own account on HCP? OR There is one common account for SuccessFactors’s extensions?

        And one more question – You wrote: “the HTML5 scenario is still not entirely supported” It’s mean that for now we can extend SuccessFactors with Java application Only? There is no possibility to add extension that is SAPUI5 Application?

        Best regards,

        A.

        (0) 
        1. Chris Paine

          You can use  sapui5 it’s just that SuccessFactors roles are not propagated, but generally that’s not a problem as if designed with Fiori principles each app should only cater for one role anyway.

          (0) 
        2. Tanya Hristova Post author

          No, the users don’t have to have an HCP account. The userbase in fact comes from SuccessFactors – it’s the SF userbase of the company.

          To allow its userbase to use an extension application running on HCP, the SF company needs to be onboarded (linked to an extension account) on HCP. That account is one per company so it’s not required for the users of the SF company to have their own HCP accounts.

          The second question was answered by Chris, though I’d like to add that hcmcloud-create-connection also works only on Java applications so the connectivity from the extension application to SF would also have to be configured manually for HTML5 applications.

          (0) 
          1. Chris Paine

            To add to Tanya’s excellent response, that means configuring the SSO for the UI5 app in provisioning. It’s not too hard, until these great console commands were public it’s how we had to do it for all extension apps.

            (0) 
            1. Agata Nowak-Mizerka

              Ok, so to have a clear picture of possibilities I would like to consider one more point.

              Suppose I have UI5 application which is used in Success Factors. This application uses oData from onPermise system( onPremise is connected by Cloud connector with HCP).

              When user starts this app, the browser shows window to login to onPermise system. What are the possibilities of joining these two accounts – from SF and onPermise?

              What I understand I need Identity Provider – for example I can use SAP Cloud Identity Service (but this is additional service – not part of HCP (right?) ). Is there any additional SAP standard tool/solution that I can use to connect these two accounts?

              (0) 
              1. Chris Paine

                The user details (principal) is passed through HCP to SAP HANA cloud connector (propagated) where an x.509 cert trust is set up between the gateway system and SAP hcc. You can use user mapping in the Gateway to map from SF user to SAP user. However, hopefully if you are using SF and on prem SAP you have created the SF users such that their user ID is same as the SAP one anyway. Look up principal propagation I  the help site for more info.

                (0) 
  2. Chris Paine

    Great wrap up of the application of the deployment tools.

    I hope that soon we will have a way to deploy custom fiori style tiles for the new homepage as well as custom to do configuration. That would be great!

    But a great write up.

    Thank you!

    (0) 
  3. Chris Paine

    Hi Tanya, I’m guessing that using the homepage tile config you have to be careful that the content in the tile is not access controlled (so it doesn’t attempt to trigger SSO) or contain any javascript. Is there any special care needed to ensure that the content doesn’t attempt to return a load balancer cookie?

    This used to be a problem when sourcing the tile html from the app.

    Thanks,

    Chris

    (0) 
  4. Tim Wernick

    Hi Tanya,

    thanks a lot for this very informative blog post. However I have some questions:

    • We have a successfactors system which is using the new fiori style tiles. Using your approach there’s no new tile showing up. At least I was not able to find it. Is there a way to do something similar with the fiori style successfactors homepage?
    • Speaking about the fiori style: Is there a way to create and upload a dynamic fiori tile which consumes an odata service using the same or a similar approach?

    Thanks for your answer in advance.

     

    kind regards

     

    Tim

    (0) 

Leave a Reply