Version 2021

SAML web application toolkit: Single sign-on to a web application

You can learn how to integrate a web application with Badge, and allow users to sign in to the web application by scanning a Badge QR code, by working with the SAML (Security Assertion Markup Language) web application toolkit. The toolkit includes a sample web application that demonstrates the following functions:

  • Logging in. You log in by scanning a Badge QR code using the Badge app on your smartphone.
  • Performing tasks in the web application. The sample web application displays a web page. When you integrate your organization's web application with Badge, users would be able to perform the tasks that they typically do using that web application.
  • Logging out.

The sample web application is a simple, Java-based application that demonstrates how you can build your own web application that integrates with Badge using the Security Assertion Markup Language (SAML) 2.0 standard. You deploy the sample web application on a Tomcat web server. Badge is the identity provider, and the web application is the service provider.

To use the SAML web application toolkit, follow the instructions provided below:

Setting up the sample web application

Follow the steps below to set up the sample web application that demonstrates logging in by scanning a Badge QR code. At a high level, the steps include the following:

  1. Request access to the SAML web application toolkit
  2. Download the Badge security app to your smartphone
  3. Create a Badge network
  4. Register the sample web application in Identity Manager
  5. Configure the sample web application to work with your Badge network

Prerequisites

Before you set up the sample web application, you should be familiar with the following:

  • Java development concepts

The machine that you build the sample web application on must meet the following requirements:

  • Apache Tomcat 7 or later
  • Java SE Development Kit (JDK) version 1.7 or later
  • Eclipse IDE for Java EE Developers version 4.4 or later

Gather the following information:

  • The server, domain name, and port to deploy the sample web application on.

The steps below provide detailed instructions for setting up the sample web application.

  1. Request access to the SAML web application toolkit
    Visit http://developer.usher.com and submit your name and contact information. MicroStrategy will provide you with the SAML web application toolkit.
    Next, download the Badge security app to your smartphone.
  2. Download the Badge security app to your smartphone
    Download the Badge app from the App Store℠ or Google Play™. Next, create a Badge network.
  3. Create a Badge network
    Your Badge network is the group of users in your organization who can use the Badge app on their smartphone to validate their identity and access resources such as web applications. Members of your network download their badge to their smartphone, then use the badge to authenticate to your systems that are integrated with Badge. To provide access through Badge, you must first create a Badge network. For detailed steps, see Creating a Badge network in the MicroStrategy Identity Help.
    Next, register the sample web application in your Badge network.
  4. Register the sample web application in Identity ManagerTo register the sample web application in your Badge network, follow the steps in Integrating a SAML-enabled web application with Badge in the MicroStrategy Identity Help. Use the following values when you register the sample web application:
    • Service Provider ID: This is the web application's service provider ID. For the sample web application, type a string or a URL. For example, com.myorg.SimpleWebApp.
    • Relay State: This is the URL that users are directed to when they log in (the SAML 2.0 RelayState parameter). Type http://server.domain.com:port/sampleSAMLizeWebApp/
      where:
      • server is the server that the sample web application is deployed on.
      • domain is the domain name of the server that the sample web application is deployed on.
      • port is the port that the sample web application is deployed on.
    • Redirect on Logout URL: This is the web page that you want to send users to when they log out of the web application. For this example, type the same value that you provided for the Relay State.
    • Assertion Consumer Service URL: This is the remote SAML sign-in URL for the sample web application. Type http://server.domain.com:port/sampleSAMLizeWebApp/usherAssertionConsumerService.jsp
      where:
      • server is the server that the sample web application is deployed on.
      • domain is the domain name of the server that the sample web application is deployed on.
      • port is the port that the sample web application is deployed on.
    • Attribute Consuming Service: This is the group of Badge user attributes that are included in the SAML assertion. Add a SAML Attribute Consuming Service that contains the following SAML Attribute Names:
      • FirstName (case-sensitive). Select the User Field that contains the user's first name.
      • LastName (case-sensitive). Select the User Field that contains the user's last name.
      • Email (case-sensitive). Select the User Field that contains the user's email address.

    5. When you finish registering the sample web application, download the Badge identity provider metadata and the Badge identity provider security certificate, and note the values provided for Login URL and Logout URL. Save the Badge security certificate in a location that is accessible from your web application. You will use these files and this information to configure the sample web application.

    Next, configure the sample web application to work with your Badge network.

  5. Configure the sample web application to work with your Badge network
    To enable the sample web application to work with Usher, modify the following files with the values described below:
    • Login URL. In the sampleSAMLizeWebApp/usherSAMLRequest.jsp file, for the idPLoginURL variable, type the Login URL that was provided when you registered the sample web application in Identity Manager. For example, String idPLoginUrl = "https://uvs-v2.usher.com/samlsso/1234";
    • Service Provider ID. In the sampleSAMLizeWebApp/usherSAMLRequest.jsp file, for the usherServiceProviderID variable, type the Service Provider ID that you specified when you registered the sample web application in Identity Manager. For example, String usherServiceProviderID="com.myorg.SimpleWebApp";
    • Logout URL. In the sampleSAMLizeWebApp/landingpage.jsp file, for the idPLogoutUrl variable, type the Logout URL that was provided when you registered the sample web application in Identity Manager. For example, String idPLogoutUrl = "https://uvs-v2.usher.com/samlslo/1234";
    • Badge identity provider security certificate. In the  sampleSAMLizeWebApp/usherAssertionConsumerService.jsp file, for the usherSAMLCertificateAbsolutePath variable, type the path to the Badge security certificate that you downloaded when you registered the sample web application in Identity Manager.

Working with the sample web application

After you set up the sample web application, you can log in to the web application by scanning a Badge QR code.

To log in to the sample web application with the Usher app

  1. In a web browser, navigate to the URL of your web application, such as http://yourdomain.com:yourport. Click Badge Login. A QR code is displayed.
  2. On your smartphone, open the Badge app, then tap the badge associated with the network that you registered the web application in. Swipe up to display the QR code reader.
  3. Scan the QR code that is displayed on your computer screen. You are logged in to the web application, and a web page with the message Hello world is displayed.