Quick Start Guide

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:

Download and install OpenJDK 8 or Oracle JDK 1.8.*.
Download and install WSO2 Identity Server - Version 5.5.0
Download and install Apache Tomcat version 7.*.* or 8.*.*
Download and install cURL.
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.
Open /etc/hosts file, add the following entry and restart the machine.
```
127.0.0.1       localhost.com
```
Tip: Make sure that this is the only such entry for this IP address in the /etc/hosts file to avoid any conflicts.

Deploying and starting the sample applications

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

Download the samples from here.
Unzip is-samples-1.0.0.zip.

Note: <IS_HOME> refers to the directory where the WSO2 Identity Server is installed. <TOMCAT_HOME> refers to the directory where your Apache Tomcat server is installed.
Navigate to is-samples-1.0.0/samples/OIDC-APPS and copy Dispatch.war and Swift.war to tomcat webapps directory.
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.
Navigate to <IS_HOME>/bin in the command line and start the server by executing wso2server.sh (for Linux) or wso2server.bin (for Windows).
Navigate to <TOMCAT_HOME>/bin and start the Tomcat server by executing catalina.sh (for Linux) or catalina.bat (for Windows).

Note: You need to run these commands from the root. You can navigate to the directory and use the following command in Linux or OSX.
sudo sh catalina.sh run
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).

Note: You need to run these commands from the root. You can navigate to the directory and use the following command in Linux or OSX.
sudo sh qsg.sh run

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

Enter 1 as scenario number.
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
This QSG uses the command line utility to do the above. To know how each can be done through the Management Console, click the below links:
a. Creating users and roles
b. Configuring service providers
c. Configuring web app for SSO
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:
Click Log in and use the following credentials:
Manager
Username: cameron
Password: cameron123
Give your consent by selecting the attribute you want to give access to as part of sharing your profile information and click Approve.

Obtaining the user consent is one of the fundamental requirements of GDPR regulation. WSO2 IS facilitates this through its Consent Management features. To know more about GDPR and how WSO2 IS handles consent, click here.
The following page is displayed for the Dispatch application and can be accessed at http://localhost:8080/saml2-web-app-dispatch.com/.
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:

Enter 2 as the scenario number.
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:
Click Log in and sign in to the web application you accessed using any of the following credentials:
Manager
Username: cameron
Password: cameron123
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.
Now open a new tab in your browser and access the other web application. For example, http://localhost:8080/Swift/. The following screen appears.

The Swift web application can be accessed without having to enter the user credentials again.

You have set up single-sign-on and your employees are happy with their experience since they only have to provide credentials once in order to access both apps.

Multi-factor authentication

Problem scenario

Pickup has a secure, hassle-free identity management system in place. However, to better protect the data resources and applications, the traditional user ID and password approach is not sufficient. You explore ways to enhance security by introducing another level of authentication and decide to use the Multi-factor Authentication (MFA) capability in WSO2 IS.

Configuring multi-factor authentication

Now, you can run the scenario:

Enter 3 to configure the Multi-factor Authentication scenario.
Enter the paths where WSO2 IS and Apache Tomcat are installed.
Enter 'y' to confirm that you have already registered an app in Twitter.
Click here for instructions on registering a Twitter app.
To try out multi-factor authentication, you must first register a Twitter application if you have not done so already.
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.
Enter the API key and the API secret of your registered Twitter application.
The following screen is displayed:
Open up a web browser and paste the application URL for Dispatch (http://localhost:8080/saml2-web-app-dispatch.com) or Swift (http://localhost:8080/saml2-web-app-swift.com). Click Log in.
Sign in to the application using the following user credentials.
Manager
Username: cameron
Password: cameron123
You are redirected to the Twitter login page (as Twitter is the second authentification factor).
Enter your Twitter username and password.
Give consent and click Approve.
After a successful authentication, you are redirected back to the web application.

Federated authentication

Problem scenario

Pickup works with a team of external consultants and you want to give them access to the web apps. However, it is a hassle to keep adding and maintaining their accounts in the employee database as these consultants are temporary and they keep rotating. Therefore, you decide to use Identity Server's identity federation capability where the external consultants can use their already existing Twitter account credentials to log in to the apps.

Configuring federated authentication

You can use the following steps to configure federated authentication using WSO2 IS:

Enter number 4 to configure Twitter a Federated Authenticator.
Enter the paths where WSO2 IS and Tomcat are installed.
Enter 'y' to confirm that you have already registered an app in Twitter.
Click here for instructions on registering a Twitter app.
To try out this federation scenario, you must first register a Twitter application if you have not done so already.
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.
Enter the API key and the API secret of your registered Twitter application.

The following screen is displayed:
Open up a web browser and paste the application URL for Dispatch (http://localhost:8080/saml2-web-app-dispatch.com) or Swift (http://localhost:8080/saml2-web-app-swift.com).
Log in to the application using the following user credentials.
Manager
Username: cameron
Password: cameron123
Give consent and click Approve.
After a successful authentication, you are redirected back to the web application.

Self sign-up

Problem scenario

Pickup is going through a major expansion and is in the process of hiring new employees. Currently, when a new employee joins, the HR team requests for their details, and creates user accounts and then asks them to verify, edit and customize their user profiles. This process sometimes takes few days and now the HR team is having a hard time doing this one by one for especially when a larger number of employees come onboard. You realize that asking new employees to self-sign up to web apps is so much easier and faster and you decide to set this up for HR with WSO2 IS which in turn saves them a lot of time and effort.

Configuring self sign-up

You can follow the below steps to configure self-sign up (allowing the users to sign-up themselves) using WSO2 IS:

Before you begin:

Open the file output-event-adapters.xml in <IS_HOME>/repository/conf directory.
Find the adapter configuration for emails and change the email address, username, password values into a valid email account.
Restart the Identity Server.

Enter 5 to select the Configuring Self-Signup scenario.
Enter the paths where WSO2 IS and Tomcat are installed.
There are three approaches to enabling users to register themselves:
1. Self User Registration (without any setting).
  This enables self-sign up in WSO2 IS without any other configuration changes. It sends an email to the user-provided email address but enables self-registration in WSO2 IS.
2. Enable account lock on creation.
  This will lock the user account during user registration. The user can only log into the app after clicking the verification link sent to the user-provided email address. A confirmation mail is sent to the user but user account is locked until the user confirms the account by clicking on the account confirmation mail sent by WSO2 IS.
3. Enable Notification Internally Management.
  This approach notifies the user of the account creation. A confirmation mail is sent to the user-provided email address but the account is locked in the process.
Select the approach you would like to try.
Open the Dispatch web application and try to log in.
In the Sign In page, click the Register Now link.
Fill the user details and create a user account.

Note: If you want a user to self register for a specific tenant, you need to provide the username in the following format: <USERNAME>@<TENAND_DOMAIN>. The following step is required only if you picked option 2 or 3 in the step (3).
Click Confirm Registration in the email or copy the link in the email to your browser to confirm the account. Once you confirm the account, the account is unlocked and an email is sent. Now you can log into the Dispatch application using the new user credentials.

The self-registration is all set and good to go. However, the HR manager still has few concerns.

Creating a workflow

Problem scenario

The HR manager is concerned about the security and prefers to review and approve new user accounts before giving them access to applications. He reaches out to you with these concerns. You realize that you can create a workflow using WSO2 IS and give role-based authorization to the HR manager to approve each account. In this workflow, whenever a new user account is created, it creates a task for the HR manager who simply approves/disapproves the user account.

Configuring workflow

The workflow feature enables you to add more control and constraints to the tasks executed within it. The workflow demonstrated here defines an approval process for new user additions. In the scenario described below, a senior manager and a junior manager have to approve each new user addition. The workflow is defined in such a way that, first, the junior manager has to approve the task followed by the senior manager approving it.

To configure this, follow the steps below:

Enter number 6 to select the Creating a workflow scenario.
Enter the paths to your WSO2 IS pack and the Tomcat pack.
Open the Dispatch web application and try to log in.
In the Sign In page, click the Register Now link.
Fill the user details and create a user account. (If you want a user to sign up by themselves for a specific tenant, you need to provide the username in the following format: <USERNAME>@<TENAND_DOMAIN>. (Even though the new user is created successfully, it is still disabled. To enable the user, you need to log in to the WSO2 dashboard and approve the pending workflow requests.)
Access the WSO2 Identity Server dashboard.
Log in to the dashboard with the junior manager’s credentials.
Username: alex
Password: alex123
Click on View Details button under Pending Approvals.
Click on the task ID.
Approve the pending task and log out of junior manager’s profile.
Log in to the dashboard with senior manager’s credentials.
Username: cameron
Password: cameron123
Click on View Details button under Pending Approvals.
Click on Task ID.

Approve the pending task and log out of the senior manager’s profile.
Log in to the Dispatch application with the new user's credentials.

This concludes the quick start. You have set up WSO2 IS and gone through the basic use cases of the product. For more advanced use cases, check our Tutorials.