Creating a Custom WS-FED Application

In this blog post I’d like to show you how to create a custom WS-Fed application on the Centrify User Portal. This may be an existing internal app or a 3rd party hosted application. As you probably know by now Centrify provides about 3,000 application profiles out of the box, but there are those cases when you might have an internally developed app or a lessor know 3rd party app that supports WS-Fed and you would like to provide it with single sign-on . I’ve included a primer on how SSO works with WS-Fed as well as detailed instructions on how to configure a custom application. And remember custom applications can still take advantage of the access controls and per applications policies and multi-factor authentication (MFA).

How SSO with WS-Fed works

Conceptually, WS-Fed authentication works much the same way as SAML authentication does. The details of what it sends are called different things, but the flow of information is similar. WS-Fed uses a different protocol than SAML, and the information that it needs in the response token is different. Below is a brief comparison between the two authentication protocols and a primer to prepare you for deploying WS-FED applications

SAML (Security Assertion Markup Language) WS-Federation (Web Services Federation)
The web application sends a SAML request to the identity provider. The web application sends Query parameters in a Request Security Token (RST) as the request to the identity provider.
After verifying the user’s identity, the identity provider returns a SAML response. Inside that SAML response is a SAML assertion. After verifying the user’s identity, the identity provider returns a Request Security Token Response (RSTR). Inside that RSTR is a SAML assertion.
You can specify to sign the SAML assertion, the SAML response, or both. RSTRs are always signed.

How SAML authentication works

Here’s an overview of each authentication step in SAML vs WS-Fed.

Step # SAML authentication step WS-Fed authentication step
1. A user visits the login page of a web application.
2. The web application generates a SAML request and redirects the user to the SSO URL. The web application generates a Request Security Token (RST) and redirects the user to the SSO URL.
3. The identity provider parses the SAML request, verifies the user’s identity in Active Directory or other user stores, and verifies the user’s identity. The identity provider parses the RST request, verifies the user’s identity in Active Directory or other user stores, and verifies the user’s identity.
4. The identity provider generates a SAML assertion in a SAML response, and sends it all back to the web application. The identity provider generates a SAML assertion inside a Request Security Token Response (RSTR), and sends it all back to the web application.
5. The web application receives the SAML response, and logs the user in to the application. The web application receives the RSTR response, and logs the user in to the application.

Gathering existing information in your WS-Fed application

Before you configure the connection between your existing WS-Fed application and the cloud service, there are a few configuration settings and so forth that you need to locate and gather. In your WS-Fed app, locate the following items:

  • Resource URI: You’ll need to enter the Resource URI into the application settings in Cloud Manager.
  • Issuer: Although it doesn’t matter what this value is, what matters is that it’s the same in your WS-Fed application and the application settings in Cloud Manager.
  • Signing certificate: Use the same certificate that you’ve uploaded to the WS-Fed application.
  • Claims details: The claims specify the user attribute information that the WS-Fed application passes in the security token. Each application may use a different set of user attributes to validate and authenticate users. For example, it could be a combination of name, email address, and perhaps also a group name. Your application should have the claim detail, or you can contact your application vendor for additional assistance.

You’ll need the aforementioned information when you go to configure the WS-Fed application in Cloud Manager.

The diagram below highlights the configuration details that you need.

 

wsfedarch

 

Adding and configuring the custom WS-Fed application

This section covers how you add the custom WS-Fed application to Cloud Manager and do some initial configuration settings.

To add and configure a generic WS-Fed application

  • In Cloud Manager, click Apps.
  • Click Add Web Apps. The Add Web Apps screen appears.
  • Click Custom.
  • On the Custom tab, next to the WS-Fed application, click Add
  • In the Add Web App screen, click Yes to add the application. Cloud Manager adds the application.
  • Click Close to exit the Application Catalog. The application that you just added opens to the Application Settings page.

generic-WSFed

  • On the Application Settings page, enter your application’s Resource URI in the Resource Application URL field.
  • On the Description page, change the name and description for the application. Because this is a generic or custom application, it’s recommended to give this application a unique name. You can also provide a custom application logo.
  • On the User Access page, select the role(s) that represent the users and groups that have access to the application. When assigning an application to a role, select either Automatic Install or Optional Install: Select Automatic Install for applications that you want to appear automatically for users. If you select Optional Install, the application doesn’t automatically appear in the user portal and users have the option to add the application.
  • (Optional) On the Policy page, specify additional authentication control for this application. You can select one or both of the following settings:
    • Intranet Only: Select this option to prevent users’ outside the company intranet from launching this application. To use this option, you must also specify which IP addresses are considered as your intranet by specifying the Corporate IP range in Settings > Corporate IP Range. Require Strong Authentication: Select this option to force users to authenticate using additional, stronger authentication mechanisms when launching an application. Specify these mechanisms in Settings > Corporate IP Range. You can also include JavaScript code to identify specific circumstances when you want to block an application or you want to require additional authentication methods. For details, see Specifying application access policies with JavaScript.
    • On the Account Mapping page, configure how the login information is mapped to the application’s user accounts. The options are as follows: Use the following Active Directory field to supply the user name: Use this option if the user accounts are based on Active Directory user attributes. Specify an Active Directory field such as mail or userPrincipalName. Everybody shares a single user name: Use this option if you want to share access to an account but not share the user name and password. For example, some people share an application developer account. Prompt the user for their user name: Use this option if you want users to supply their own user name and password. The first time a user launches the application, he enters his login credentials for that application. The cloud service stores the user name and password and the next time the user launches the application, the cloud service logs the user in automatically. Use this script: You can customize the user account mapping here by supplying a custom JavaScript script. For example, you could use the following line as a script: LoginUser.Username = LoginUser.Get(‘mail’)+’.ad’; The above script instructs the cloud service to set the login user name to the user’s mail attribute value in Active Directory and add ‘.ad’ to the end. So, if the user’s mail attribute value is Adele.Darwin@acme.com then the cloud service uses Adele.Darwin@acme.com.ad. For more information about writing a script to map user accounts, see the User-password application scripting guide.
  • (Optional) On the Changelog page, you can see recent changes that have been made to the application settings, by date, user, and the type of change that was made.
  • Click Save. Next, you’re ready to edit the Advanced Script.