/
Quick Start Guide
com.atlassian.confluence.content.render.xhtml.migration.exceptions.UnknownMacroMigrationException: The macro 'next_previous_links' is unknown.

Quick Start Guide

Mar 19, 2019

WSO2 Identity Server (WSO2 IS) provides identity management across many platforms such as enterprise applications, services, and APIs. In other words, it provides a comprehensive solution that allows you to manage the identity and access management (IAM) activities of an enterprise. The Quick Start Guide takes you on a quick tour of WSO2 IS to help you understand what you can achieve using this product. 

Let us consider a fictional cab company called Pickup, where WSO2 IS is used as the identity and access management solution to cater to many of its identity use cases. Pickup has several identities to manage, many sets of credentials per person for each application, identify security vulnerabilities, permission levels and many more. Cameron, a manager at Pickup, is responsible for implementing WSO2 IS to find solutions to these IAM related issues. 

Introducing the sample

This QSG describes some common use cases that Cameron comes across and how WSO2 IS is used to address each of these use cases. Each business use case (scenario) is demonstrated using a sample that contains two web apps - Dispatch and Swift that are configured and run using a command line utility. A brief description of these two apps are given below:

Dispatch - A management application used to manage the overall operations at Pickup.

Swift - A vehicle allocation application used to allocate drivers to vehicles at Pickup.

Assume you are Cameron and you are assigned to find solutions to the various identity-related use cases. Let's see how this QSG can guide you to demonstrate these use cases and how you can use WSO2 IS to resolve them. 

Prerequisites

First, you need to make sure that the following requirements are met:

  1. Download and install OpenJDK 8 or Oracle JDK 1.8.*.

  2. Download and install WSO2 Identity Server - Version 5.5.0

  3. Download and install Apache Tomcat version 7.*.* or 8.*.*

  4. Download and install cURL.

  5. To try out multi-factor authentication or federated authentication, you must first create a Twitter application. 

    1. Go to https://twitter.com/ and create an account.

    2. Register a new application on Twitter at https://apps.twitter.com. For more information, see Create Twitter Application. 
      You can use the following URL as the Callback URL for your twitter app: https://localhost:9443/commonauth.

    3. Note down the API key and secret for later use.

  6. Open /etc/hosts file, add the following entry and restart the machine.

    127.0.0.1 localhost.com

Deploying and starting the sample applications

Now, follow the steps below to configure and run the samples:

  1. Download the samples from here. 

  2. Unzip is-samples-1.0.0.zip.

  3. Navigate to is-samples-1.0.0/samples/OIDC-APPS and copy Dispatch.war and  Swift.war to tomcat webapps directory.

  4. Navigate to is-samples-1.0.0/samples/SAML2-APPS and copy saml2-web-app-dispatch.com.war and saml2-web-app-swift.com.war to tomcat webapps directory.

  5. Navigate to <IS_HOME>/bin in the command line and start the server by executing wso2server.sh (for Linux) or wso2server.bin (for Windows).

  6. Navigate to <TOMCAT_HOME>/bin and start the Tomcat server by executing catalina.sh (for Linux) or catalina.bat (for Windows).

  7. Navigate to is-samples-1.0.0/samples/ QSG-bundle/QSG/bin and start the Quick Start Guide by executing qsg.sh (for Linux) or qsg.bat (for Windows).

The samples are deployed and the WSO2 Identity Server is up and running. Now you can use the command line utility to demonstrate each of the identity use case scenarios. 

Single sign-on

Problem scenario

The first problem that Pickup faces is that the web apps are separate, and each user must have two separate credentials to log in to each application. 

When the number of applications increase, having different credentials for each application is not a scalable solution. You realize that the best way to overcome this situation is to have a solution where the users who get authenticated and given access to one application are also authenticated to other applications automatically. In other words, it needs a single sign-on (SSO) solution that enables authentication of the user for both applications using a single set of credentials. You decide to use WSO2 IS to configure SSO.  

You can use the command line utility to configure SAML SSO for the web apps as described in the steps below (if SAML2 is used as the authentication protocol for both apps).

Configuring single sign-on with SAML2

  1. Enter 1 as scenario number.

  2. Enter the paths to your WSO2 IS pack and the Tomcat pack.

                                                                                                                                                                                                                                                                                                                                                   
    Running scenario 1:

    • creates two users - Cameron and Alex 

    • creates the role 'manager' and assigns that role to Cameron

    • creates service providers for two web apps

    • configures SAML2 web SSO for Dispatch and Swift 

    Once the above step is done, it displays the following screen:


    Now you can open the web applications by entering the following URL in a web browser.
    Dispatch: http://localhost:8080/saml2-web-app-dispatch.com/
    Swift: http://localhost:8080/saml2-web-app-swift.com/ 

    The following Login screen is displayed:

  3. Click Log in and use the following credentials:Manager 
    Username: cameron
    Password: cameron123

  4. Give your consent by selecting the attribute you want to give access to as part of sharing your profile information and click Approve.

    The following page is displayed for the Dispatch application and can be accessed at http://localhost:8080/saml2-web-app-dispatch.com/.

  5. Now open a new tab in your browser and access http://localhost:8080/saml2-web-app-swift.com/. You see the following page for the Swift application.


    The Swift application opens without having to enter the user credentials again.

Configuring single sign-on with OIDC

If the two applications are using OIDC as their authentication protocol, You can follow the steps below:

  1. Enter 2 as the scenario number.

  2. Enter the paths to your WSO2 IS pack and the Apache Tomcat pack.


    Running scenario 2, creates two users (Cameron and Alex), a role as 'manager' and assigns the role to Cameron. It also creates service providers for each application and configures SSO for them. 
    Once this scenario is run, the following screen is displayed:

    Once you open the web applications by entering the following URL in a web browser (Dispatch: http://localhost:8080/Dispatch/ or Swift: http://localhost:8080/Swift/), the following login screen appears:

  3. Click Log in and sign in to the web application you accessed using any of the following credentials:Manager 
    Username: cameron
    Password: cameron123

  4. In the OPENID USER CLAIMS page, select the approval type and give the consent by selecting the attribute you wish to share with the service provider and click Continue. 


    The following page appears if you accessed http://localhost:8080/Dispatch/. The Swift application opens if you attempted to access that instead.

  5. Now open a new tab in your browser and access the other web application. For example, http://localhost:8080/Swift/. The following screen appears.

com.atlassian.confluence.content.render.xhtml.migration.exceptions.UnknownMacroMigrationException: The macro 'next_previous_links2' is unknown.