

Deploying the Sample Applications¶

This topic provides instructions on how to download and deploy the sample application used while trying out sample use cases in WSO2 Identity Server.

Before you begin

Download Apache Tomcat 8.x from here and install. Tomcat server installation location will be referred as <TOMCAT_HOME> later in this guide.

Note

It is recommended that you use a hostname that is not localhost to avoid browser errors. Modify the /etc/hosts entry in your machine to reflect this. Note that localhost is used in this documentation as an example, but you must modify this when configuring the authenticators or connectors with this sample application.

Deploying the Travelocity webapp¶

Before you begin

Install Apache Tomcat 8.x as explained in the beginning of this document.

Download the sample¶

To be able to deploy a WSO2 Identity Server sample, you need to download it onto your machine first.

Follow the instructions below to download a sample from GitHub.

Navigate to WSO2 Identity Server Samples.
Download the travelocity.com.war file from the latest release assets.

Deploy the sample web application¶

Deploy this sample web app on a web container.

Copy the travelocity.com.warfile into the webapps folder. For example, <TOMCAT_HOME>/apache-tomcat-<version>/webapps
Open a terminal window and add the following entry to the /etc/hosts file of your machine to configure the hostname.
```
127.0.0.1   wso2is.local
127.0.0.1   localhost.com
```
Why is this step needed?

Some browsers do not allow you to create cookies for a naked hostname, such as localhost. Cookies are required when working with SSO . Therefore, to ensure that the SSO capabilities work as expected in this tutorial, you need to configure the etc/host file as explained in this step.

The etc/host file is a read-only file. Therefore, you won't be able to edit it by opening the file via a text editor. Instead, edit the file using the terminal commands.
For example, use the following command if you are working on a Mac/Linux environment.
```
sudo nano /etc/hosts
```
Open the travelocity.properties file found in the <TOMCAT_HOME>/webapps/travelocity.com/WEB-INF/classes directory and configure the following property with the hostname ( wso2is.local ) that you configured above. Finally restart the tomcat server.
```
#The URL of the SAML 2.0 Assertion Consumer
SAML2.AssertionConsumerURL=http://wso2is.local:8080/travelocity.com/home.jsp
```
Start the Tomcat server.

To check the sample application, navigate to http://<TOMCAT_HOST>:<TOMCAT_PORT>/travelocity.com/index.jsp on your browser.

For example, http://wso2is.local:8080/travelocity.com/index.jsp

Tip

If you wish to change properties like the issuer ID, consumer URL, and IdP URL, you can edit the travelocity.properties file found in the travelocity.com/WEB-INF/classes directory. Also if the service provider is configured in a tenant you can use "QueryParams" property to send the tenant domain.For example, "QueryParams=tenantDomain=wso2.com".

This sample uses the following default values.

Properties	Description
`SAML2.SPEntityId=travelocity.com`	A unique identifier for this SAML 2.0 Service Provider application
`SAML2.AssertionConsumerURL= http://wso2is.local:8080/travelocity.com/home.jsp`	The URL of the SAML 2.0 Assertion Consumer
`SAML2.IdPURL= https://localhost:9443/samlsso`	The URL of the SAML 2.0 Identity Provider
`SAML2.IsPassiveAuthn=true`	Set this to send SAML2 passive authentication requests

If you edit the travelocity.properties file, you must restart the Apache Tomcat server for the changes to take effect.

Configuring the service provider¶

Important

SAML2 POST Binding requires CORS configurations. Before configuring the service provider, add the following configurations to the <IS_HOME>/repository/conf/deployment.toml file to allow HTTP POST requests.

[cors]
allow_generic_http_requests = true
allow_any_origin = false
allowed_origins = [
    "http://localhost:8080", "http://localhost.com:8080"
]
allow_subdomains = false
supported_methods = [
    "GET",
    "POST",
    "HEAD",
    "OPTIONS"
]
support_any_header = true
supported_headers = []
exposed_headers = []
supports_credentials = true
max_age = 3600
tag_requests = false

The next step is to configure the service provider.

Return to the WSO2 IS management console.
Navigate to Main>Identity>Service Providers and click Add.
Enter travelocity.com in the Service Provider Name text box, and click Register.
In the Inbound Authentication Configuration section, click Configure under the SAML2 Web SSO Configuration section.
1. Now set the configurations as follows:
  1. Issuer : travelocity.com
  2. Assertion Consumer URL : http://wso2is.local:8080/travelocity.com/home.jsp
    Click Yes, in the message that appears.
2. Select the following check-boxes:
  1. Enable Response Signing
  2. Enable Single Logout
  3. Enable Attribute Profile
  4. Include Attributes in the Response Always
  5. Enable Signature Validation in Authentication Requests and Logout Requests
Tip

For more information on the advanced configurations refer, Configuring SAML2 WEB Single-Sign-On
Click Register to save the changes.
Now you are sent back to the Service Providers page.

Deploying the Playground2 webapp¶

Before you begin

Install Apache Tomcat 8.x as explained in the beginning of this document.

Download the sample¶

To be able to deploy a WSO2 Identity Server sample, you need to download it onto your machine first.

Follow the instructions below to download a sample from GitHub.

Navigate to WSO2 Identity Server Samples.
Download the playground2.war file from the latest release assets.

Deploy the sample web app¶

Deploy this sample web app on a web container.

Copy the the playground2.war file from the latest release assets. file into the webapps folder. For example, <TOMCAT_HOME>/apache-tomcat-<version>/webapps .
Start the Tomcat server.

Note

To check the sample application, navigate to http://<TOMCAT_HOST>:<TOMCAT_PORT>/playground2/oauth2.jsp on your browser.

For example, http://localhost:8080/playground2/oauth2.jsp

Make sure to update the param-value parameter in the WEB-INF/web.xml file with the server URL of the Identity Server if required.
Make sure to enter the port the application is running on, in the URL. If you have started the Identity Server with a port off set, then the respective port needs to be configured here.
```
<init-param>
    <description>serverUrl</description>
    <param-name>serverUrl</param-name>
    <param-value>https://localhost:9443/services/</param-value>
</init-param>
```
Info

Note that localhost is the server that hosts WSO2 Identity Server and 9443 is the default SSL port of it. Since playground application is accessing the admin service OAuth2TokenValidationService, you should have the correct serverUrl, username and password.

Update param-value parameter with credentials of an admin user if required.

<init-param>
    <description>userName</description>
    <param-name>userName</param-name>
    <param-value>admin</param-value>
</init-param>
<init-param>
    <description>password</description>
    <param-name>password</param-name>
    <param-value>admin</param-value>
</init-param>

Restart Apache Tomcat and access http://wso2is.local:8080/playground2/
By default Tomcat runs on port 8080. If you have configured it to run on a different port make sure to update the URL and access the playground application.
You are directed to the landing page of the sample application. Click on Import Photos and the following page appears.

Are you getting the error that is given below?

javax.net.ssl.SSLHandshakeException: sun.security.validator.ValidatorException: PKIX path building failed:          sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target

The sample applications do not have a keystore in them. Therefore, after changing the tomcat hostname you might get this error because the public key of the WSO2 Identity Server does not exist in the Java certificate store.

Configuring the service provider¶

The next step is to configure the service provider.

Return to the WSO2 IS management console.
Navigate to Main>Identity>Service Providers and click Add.
Enter playground2 in the Service Provider Name text box, and click Register.
Expand the Inbound Authentication Configuration section and then the OAuth/OpenID Connect Configuration and click Configure.
Fill in the form that appears. For the Allowed Grant Types, you can disable the ones you do not require or block.

Note

The grant type highlighted below is a custom grant type. This will only appear on the UI if you have configured the JWT grant type. The value specified as the name of the oauth.custom_grant_type in the deployment.toml file when creating the custom grant type is the value that will appear on the UI. For more information on writing a custom grant type, see Writing a Custom OAuth 2.0 Grant Type.
Fill the Callback Url field.

Example : http://wso2is.local:8080/playground2/oauth2client

Tip

For more information on Callback Url field and other advanced configurations refer, Configuring OAuth2-OpenID Connect Single-Sign-On
Click Add. Note that client key and client secret get generated.
Update the service provider you have created by clicking the update button.

Deploying the saml2-web-app-pickup-dispatch webapp¶

Before you begin

Install Apache Tomcat 8.x as explained in the beginning of this document.
Note that this sample uses SAML2.

Download the samples¶

To be able to deploy a WSO2 Identity Server sample, you need to download it onto your machine first.

Follow the instructions below to download a sample from GitHub.

Navigate to WSO2 Identity Server Samples.
Download the saml2-web-app-pickup-dispatch.com.war file from the latest release assets.

Deploy the sample web app¶

Deploy this sample web app on a web container.

Copy the .war file into the webapps folder. For example, <TOMCAT_HOME>/apache-tomcat-<version>/webapps .
Start the Tomcat server.

To check the sample application, navigate to http://<TOMCAT_HOST>:<TOMCAT_PORT>/saml2-web-app-pickup-dispatch.com/index.jsp on your browser.

For example, http://localhost:8080/saml2-web-app-pickup-dispatch.com/index.jsp .

Configuring the service provider¶

The next step is to configure the service provider.

Return to the WSO2 IS management console.
Navigate to Main>Identity>Service Providers and click Add.
Enter saml2-web-app-pickup-dispatch in the Service Provider Name text box, and click Register.
In the Inbound Authentication Configuration section, click Configure under the SAML2 Web SSO Configuration section.
1. Now set the configuration as follows:
  1. Issuer : saml2-web-app-pickup-dispatch.com
  2. Assertion Consumer URL : http://localhost.com:8080/saml2-web-app-pickup-dispatch.com/home.jsp
    Click Yes, in the message that appears.
2. Select the following check-boxes:
  1. Enable Response Signing
  2. Enable Single Logout
  3. Enable Attribute Profile
  4. Include Attributes in the Response Always
  5. Enable Signature Validation in Authentication Requests and Logout Requests
Tip

For more information on the advanced configurations refer, Configuring SAML2 WEB Single-Sign-On
Click Register to save the changes.
Now you are sent back to the Service Providers page.

Deploying the saml2-web-app-pickup-manager webapp¶

Before you begin

Install Apache Tomcat 8.x as explained in the beginning of this document.
Note that this sample uses SAML2.

Download the sample¶

To be able to deploy a WSO2 Identity Server sample, you need to download it onto your machine first.

Follow the instructions below to download a sample from GitHub.

Navigate to WSO2 Identity Server Samples.
Download the saml2-web-app-pickup-manager.com.war file from the latest release assets.

Deploy the sample web app¶

Deploy this sample web app on a web container.

Copy the .war file into the webapps folder. For example, <TOMCAT_HOME>/apache-tomcat-<version>/webapps .
Start the Tomcat server.

To check the sample application, navigate to http://<TOMCAT_HOST>:<TOMCAT_PORT>/saml2-web-app-pickup-manager.com/index.jsp on your browser.

For example, http://localhost:8080/saml2-web-app-pickup-manager.com/index.jsp .

Configuring the service provider¶

Important

SAML2 POST Binding requires CORS configs set up. Before configuring the service provider, make sure you add the following configurations to the <IS_HOME>/repository/conf/deployment.toml file to allow HTTP POST requests.

[cors]
allow_generic_http_requests = true
allow_any_origin = false
allowed_origins = [
    "http://localhost:8080", "http://localhost.com:8080"
]
allow_subdomains = false
supported_methods = [
    "GET",
    "POST",
    "HEAD",
    "OPTIONS"
]
support_any_header = true
supported_headers = []
exposed_headers = []
supports_credentials = true
max_age = 3600
tag_requests = false

The next step is to configure the service provider.

Return to the WSO2 IS management console.
Navigate to Main>Identity>Service Providers and click Add.
Enter saml2-web-app-pickup-manager in the Service Provider Name text box, and click Register.
In the Inbound Authentication Configuration section, click Configure under the SAML2 Web SSO Configuration section.
1. Now set the configuration as follows:
  1. Issuer : saml2-web-app-pickup-manager.com
  2. Assertion Consumer URL : http://localhost.com:8080/saml2-web-app-pickup-manager.com/home.jsp
    
    Click Yes, in the message that appears.
2. Select the following check-boxes:
  1. Enable Response Signing
  2. Enable Single Logout
  3. Enable Attribute Profile
  4. Include Attributes in the Response Always
  5. Enable Signature Validation in Authentication Requests and Logout Requests
Tip

For more information on the advanced configurations refer, Configuring SAML2 WEB Single-Sign-On
Click Register to save the changes.
Now you are sent back to the Service Providers page.

Deploying the pickup-dispatch webapp¶

Before you begin

Install Apache Tomcat 8.x as explained in the beginning of this document.
Note that this sample uses OpenID Connect.

Download the samples¶

To be able to deploy a WSO2 Identity Server sample, you need to download it onto your machine first.

Follow the instructions below to download a sample from GitHub.

Navigate to WSO2 Identity Server Samples.
Download the pickup-dispatch.war file from the latest release assets.

Configuring the service provider¶

The first step is to configure the service provider.

Return to the WSO2 IS management console.
Navigate to Main>Identity>Service Providers and click Add.
Enter pickup-dispatch in the Service Provider Name text box, and click Register.
In the Inbound Authentication Configuration section, click Configure under the OAuth/OpenID Connect Configuration section.
Enter the following value as the Callback URL: http://localhost.com:8080/pickup-dispatch/oauth2client

Tip

The callback URL is the service provider URL to which the authorization codes are sent. Upon successful authentication, the browser should be redirected to this URL.
Click Add. Note the OAuth Client Key and Client Secret that is displayed. You will need these values later on when deploying the sample application.

Tip

For more information on the advanced configurations refer, Configuring OAuth2-OpenID Connect Single-Sign-On
Click Register to save the changes.
Now you are sent back to the Service Providers page.

Deploy the sample web app¶

Next, deploy the sample web app on a web container.

Extract the pickup-dispatch.war file and open the dispatch.properties file located in the <EXTRACT>/WEB-INF/classes folder.
Replace the consumerKey and consumerSecret values with the OAuth client key and OAuth client secret values that were generated for the newly created service provider.
Next, copy the extracted and modified pickup-dispatch folder to the <TOMCAT_HOME>/webapps folder.
Start the Tomcat server.

To check the sample application, navigate to http://<TOMCAT_HOST>:<TOMCAT_PORT>/pickup-dispatch/home.jsp on your browser.

For example, http://localhost.com:8080/pickup-dispatch/home.jsp .

Deploying the pickup-manager webapp¶

Before you begin

Install Apache Tomcat 8.x as explained in the beginning of this document.
Note that this sample uses OpenID Connect.

Download the sample¶

To be able to deploy a WSO2 Identity Server sample, you need to download it onto your machine first.

Follow the instructions below to download a sample from GitHub.

Navigate to WSO2 Identity Server Samples.
Download the pickup-manager.war file from the latest release assets.

Configuring the service provider¶

The first step is to configure the service provider.

Return to the WSO2 IS management console.
Navigate to Main>Identity>Service Providers and click Add.
Enter pickup-manager in the Service Provider Name text box, and click Register.
In the Inbound Authentication Configuration section, click Configure under the OAuth/OpenID Connect Configuration section.
Enter the following value as the Callback URL: http://localhost.com:8080/pickup-manager/oauth2client

Tip

The callback URL is the service provider URL to which the authorization codes are sent. Upon successful authentication, the browser should be redirected to this URL.
Click Add. Note the OAuth Client Key and Client Secret that is displayed. You will need these values later on when deploying the sample application.

Tip

For more information on the advanced configurations refer, Configuring OAuth2-OpenID Connect Single-Sign-On
Click Register to save the changes.
Now you are sent back to the Service Providers page.

Deploy the sample web app¶

Next, deploy the sample web app on a web container.

Extract the pickup-manager.war file and open the manager.properties file located in the <EXTRACT>/WEB-INF/classes folder.
Replace the consumerKey and consumerSecret values with the OAuth client key and OAuth client secret values that were generated for the newly created service provider.
Next, copy the extracted and modified pickup-manager folder to the <TOMCAT_HOME>/webapps folder.
Start the Tomcat server.

To check the sample application, navigate to http://<TOMCAT_HOST>:<TOMCAT_PORT>/pickup-manager/home.jsp on your browser.

For example, http://localhost.com:8080/pickup-manager/home.jsp .

Deploying the photo-editor and photo-viewer webapps¶

Before you begin

Install Apache Tomcat 8.x as explained in the beginning of this document.

Download the samples¶

To be able to deploy a WSO2 Identity Server sample, you need to download it onto your machine first.

Follow the instructions below to download the samples from GitHub.

Navigate to WSO2 Identity Server Samples.
Download the photo-edit.war file from the latest release assets.
Download the photo-view.war file from the latest release assets.

Deploy the sample web app¶

Deploy the sample web apps on a web container.

Copy the .war files into the webapps folder. For example, <TOMCAT_HOME>/apache-tomcat-<version>/webapps .
Start the Tomcat server.

To check the photo-edit sample application, navigate to http://<TOMCAT_HOST>:<TOMCAT_PORT>/photo-edit/index.jsp on your browser.

For example, ` http://localhost.com:8080/photo-edit/index.jsp .

Note

The default password configuration for photo-editor and photo-viewer is admin. If a different password needs to be used to test the samples, change the hardcoded password in <TOMCAT_HOME>/webapps/photo-view/WEB-INF/classes/apptwo.properties or <TOMCAT_HOME>/webapps/photo-edit/WEB-INF/classes/apptwo.properties.
All the directories of the tomcat server should be accessible even without root access. Otherwise, the application fails due to insufficient permissions. `

Configuring the service provider¶

Once the application is deployed, the relevant service providers are created on the management console using dynamic client registration. Follow the steps below to view the service providers and the configurations.

Return to the WSO2 IS management console.
Navigate to Main>Identity>Service Providers and click List. Note that the photo-editor and photo-view service providers have been created using dynamic client registration.
Click Edit to view the photo-editor and photo-view service provider configurations.
Expand Inbound Authentication Configuration section and then expand OAuth/OpenID Connect Configuration.
Click Edit to view the OAuth/OpenID Connect configurations.

Note that the urn:ietf:params:oauth:grant-type:uma-ticket grant type has been enabled for the photo-viewer application along with the code and password grant types.

Deploying the PassiveSTSSampleApp webapp¶

Before you begin

Install Apache Tomcat 8.x as explained in the beginning of this document.

Download the sample¶

To be able to deploy a WSO2 Identity Server sample, you need to download it onto your machine first.

Follow the instructions below to download a sample from GitHub.

Navigate to WSO2 Identity Server Samples.
Download the PassiveSTSSampleApp.war file from the latest release assets.

Deploy the sample web app¶

Deploy this sample web app on a web container.

Copy the .war file into the webapps folder. For example, <TOMCAT_HOME>/apache-tomcat-<version>/webapps .
Start the Tomcat server.

Configure sample properties¶

Open the <TOMCAT_HOME>/apache-tomcat-<version>/webapps/PassiveSTSSampleApp/WEB-INF/web.xml file and configure the following.

Specify idpUrl as the URL of Identity Server's Passive STS. The following is an example.

<init-param>
        <param-name>idpUrl</param-name>
        <param-value>https://localhost:9443/passivests</param-value>
</init-param>

Specify the replyURL as the URL of the web app. The following specifies PassiveSTSSampleApp as the web app.

<init-param>
        <param-name>replyUrl</param-name>
        <param-value>http://localhost:8080/PassiveSTSSampleApp/index.jsp</param-value>
</init-param>

Specify the realm . This should be a unique identifier for the web app as seen in the example below.

<init-param>
        <param-name>realm</param-name>
        <param-value>PassiveSTSSampleApp</param-value>
</init-param>

For tenant user logins, specify the tenantDomain .

<init-param>
        <param-name>requestParams</param-name>
        <param-value>tenantDomain=tenant4.com</param-value>
</init-param>

Restart the tomcat server.

To check the sample application, navigate to http://<TOMCAT_HOST>:<TOMCAT_PORT>/PassiveSTSSampleApp/home.jsp on your browser.

For example, http://localhost:8080/PassiveSTSSampleApp/home.jsp .

Configuring the service provider¶

The next step is to configure the service provider.

Return to the WSO2 IS management console.
Navigate to Main>Identity>Service Providers and click Add.
Enter PassiveSTSSampleApp in the Service Provider Name text box, and click Register.
In the Inbound Authentication Configuration section, click Configure under the WS-Federation (Passive) Configuration section.
1. Now set the configuration as follows:
  1. Passive STS Realm: : PassiveSTSSampleApp
  2. Assertion Consumer URL : http://localhost:8080/PassiveSTSSampleApp/index.jsp
    
    Click Yes, in the message that appears.
Tip

For more information on the advanced configurations refer, Configuring WS-Federation
Expand the Claim Configuration section and click Add Requested Claim to add the following claims.
1. http://wso2.org/claims/username
2. http://wso2.org/claims/emailaddress
Select http://wso2.org/claims/emailaddress as the Subject Claim URI.
Click Update to save the changes.
Now you are sent back to the Service Providers page.

Top