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

Using Identity Federation for a SaaS Platform (Platform version 8.1.0 and earlier)

Note: Platform version 8.1.0 introduced changes to the federation model of the Platform. Per tenant federation is no longer supported, and this page has been removed from the Account Portal. Contact your Account Administrator for more information if you have questions on federation.

Setting up Identity Federation and Adding Users

As an alternative to creating Platform Users that are authenticated through Apprenda by means of a unique Platform password, some Organizations may wish to make use of Apprenda’s Identity Federation capabilities.  In order to use Identity Federation, the feature must be enabled by the Platform Operator. Also, your Organization must first set up a relationship with a Secure Token Service (STS), a third-party entity that serves as a database by which your Organization’s members can use a single login ID and password to access other spaces that required login authentication (such as Apprenda).

If your Platform Operator has enabled Identity Federation, you will see an Identity Federation link in the upper right side of your Account Profile page.

To set up Identity Federation, click on the Identity Federation link, which will take you to the Identity Federation setup page:
 

As per the directions on the setup page, you will need to perform the following steps:

1.  Provide the URL to your STS metadata listing, and click Load.  If the data loads correctly, you will be provided with a URL that you must give to your STS administrator so that the appropriate trust relationship can be established.  An Edit button will also appear, which will allow you to alter this information (if, for instance, your STS changes)

2.  Based on the information provided in Step 1, the claims list on the right side under Step 2 will be populated with information such as name and e-mail address.  You can use the pulldown menus to decide what information from your STS will link to the corresponding Apprenda label to the left.  Please note that you must map an e-mail address to the Apprenda Email Address label, as this is the information Apprenda uses to link each Platform User Account to the appropriate STS User.

3. Test your settings by pasting the link in Step 3 in either a “private” browser session or a different browser altogether.  If your test is not successful, contact your STS administrator.  If your test is successful, you will be promted to login with STS credentials, after which you will see a page such as this:

4.  Click on the Enable Identity Federation button.

5.  All that is left now is to upload the User names and e-mail addresses that you would like to import from your STS.  To do this, simply create and upload a CSV file (a specially formatted plain text file) that contains User information as follows:

 

Once you have successfully uploaded your Users, they will appear in list of Platform Users in the Users section of the Account Portal.  Although Platform Users created through the Account Portal receive e-mails with a link that allows them to set up a password, Users added through Identity Federation will not receive such an e-mail, as they should already have a login ID and password associated with your STS.  To access the Account Portal, these Users should navigate to http://apps.[yourApprendainstance]/account.  Once there, they will be asked to enter their e-mail address, which will direct them to the login page for your STS.  After entering their login information, they will be redirected to the Account Portal.

Adding Additional Users

After the initial Identity Federation set-up, you can add additional Users (for instance, new employees who have been added to your STS) by returning to the Identity Federation page and repeating Step 5 with a CSV file containing their information.  You also may add Users manually via the Users page. As long as the e-mail addresses involved match up with those of Users set up through your STS, your newly added Users will be able to access the Account Portal by the same means outlined above.

Should the need arise, you can also create Platform User accounts for members of your Organization who do not have a login ID and password for your STS.  To do this, simply create a new Platform User.  Although the new User will not automatically receive a password setup e-mail when Identity Federation is enabled, they can use the Forgot Your Password? link found on the login page for your Apprenda instance to establish a password.

Troubleshooting and Disabling Identity Federation

You may disable Identity Federation at any time by returning to the Identity Federation page and clicking on the Disable Identity Federation button in the section for Step 4.  At this point, Users who access the Account Portal through their STS information will no longer be able to log in.  They can, however, establish Apprenda passwords for their User Accounts by clicking on the Forgot Your Password? link found on the login page for your Apprenda instance to establish a password.

When Identity Federation is enabled, Users who have both an Apprenda password and an STS identity can access the Account Portal through either method.  The User who initially set up Identity Federation, for instance, had to establish a Platform User Account and password in order to login and set up Identity Federation.

Should something go awry with your STS mappings, a User with the appropriate Account Portal Securable permissions (such as the Account Administrator) can always log in with their Apprenda login and password and then either disable Identity Federation or adjust Identity Federation settings as needed.