Open in app

Sign in

Write

Sign in

Externally Hosting WSO2 Identity Server Portals

Imalsha Gunasekara
6 min readDec 13, 2022
Vector created by freepick

If you have used WSO2 Identity Server you should know that there are several webapps hosted inside the server catering to different needs. These webapps can be found inside the $IS_HOME/repository/deployment/server/webapps folder of the Identity Server.

These applications are automatically deployed during IS server startup and are useful for different purposes such as authentication, account recovery, etc. But what if you have the requirement to host these webapps in an external server in case you need to have your own customizations to be implemented on these web apps… Just copying the webapp from the IS server and hosting them externally won’t work.

Here in this article, I will show you how you can host the following applications in an external server that you desire.

  • Authentication endpoint
  • Console app
  • Myaccount app

First of all, let us start off my building the apps so that they can be hosted independently from the IS.

Building the Portals

Authentication Portal

The authentication portal exposes the authentication endpoints that are used during the IS authentication flow. When a user accesses a webapp which is authenticated through the Identity Server, the user is redirected to the login page hosted by the authentication portal and will be authenticated through that authentication endpoint. This authentication portal is normally hosted inside the Identity Server itself and the authentication endpoint is generally available at https://localhost:9443/authenticationendpoint.

But if there is a a requirement to customize this authentication portal for purposes such as custom theming and branding, this portal can be hosted outside the IS in an external server.

Here, I will show you how to build the authentication portal from the latest IS 6.1.0-m1 pack (by the time of writing), so that it can be hosted in an external tomcat server.

  1. Download the IS pack (In this tutorial, I will be using the wso2is-6.1.0-m1 pack) and extract it inside a new folder.

2. Download the setup-authentication-endpoint.sh script and run it inside the folder containing the IS pack.

sh setup-authentication-endpoint.sh

This will extract the authentication portal webapp from the given IS pack and add it to the tomcat webapps folder with the needed libraries for it to be externally hosted.

3. Open the <TOMCAT_HOME>/webapps/authenticationendpoint/WEB-INF/web.xml file and make the following config changes to point to Identity Server URLs.

    <context-param>
        <param-name>IdentityServerEndpointContextURL</param-name>
        <param-value>https://localhost:9443</param-value>
    </context-param>
    <context-param>
        <param-name>IdentityManagementEndpointContextURL</param-name>
        <param-value>https://localhost:9443/accountrecoveryendpoint</param-value>
    </context-param>
    <context-param>
        <param-name>EnableRecoveryEndpoint</param-name>
        <param-value>true</param-value>
    </context-param>
    <context-param>
        <param-name>EnableSelfSignUpEndpoint</param-name>
        <param-value>true</param-value>
    </context-param>
    <context-param>
        <param-name>AuthenticationRESTEndpointURL</param-name>
        <param-value>https://localhost:9443/api/identity/auth/v1.1/</param-value>
    </context-param>

4. Navigate to <TOMCAT_HOME>/webapps/authenticationendpoint/WEB-INF/classes/EndpointConfig.properties file and change the config

identity.server.origin=${carbon.protocol}://${carbon.host}:${carbon.management.port}

to

identity.server.origin=https://localhost:9443

5. Navigate to <TOMCAT_HOME>/webapps/authenticationendpoint/WEB-INF/classes/RecoveryEndpointConfig.properties file and uncomment the following line.

identity.server.service.contextURL=https://localhost:9443

In order to use a secure HTTPS connection for the authentication endpoint, the keystore and trustore should be configured for the tomcat server. In this tutorial, as we are hosting the portal and the IS in the same local machine, I will be using the same keystore and truststore as of the IS server, for the tomcat. Keep in mind that in an actual environment you will need to create a new keystore and truststore for tomcat and add that location in the below steps. For more details on importing the public certificates, follow the steps 8 & 9 in the IS documentation.

  1. Open the <TOMCAT_HOME>/conf/server.xml file and enable the https connector on 8443 port.
    <Connector 
          port="8443"
          protocol="org.apache.coyote.http11.Http11NioProtocol"
          maxThreads="150"
          SSLEnabled="true"
          scheme="https"
          secure="true"
          clientAuth="want"
          sslProtocol="TLS"
          sslEnabledProtocols="TLSv1,TLSv1.1,TLSv1.2"
          keystoreFile="<TOMCAT_HOME>/conf/wso2carbon.jks"
          keystorePass="wso2carbon"
          truststoreFile="<TOMCAT_HOME>/conf/client-truststore.jks" 
          truststorePass="wso2carbon"
    />

Copy the wso2carbon.jks and client-truststore.jks files in the $IS_HOME/repository/resources/security folder inside the IS pack, to the <TOMCAT_HOME>/conf folder and add that location to the keystoreFile and truststoreFile configs.

3. Open <TOMCAT_HOME>/bin/catalina.sh and add the following JAVA_OPTS.

JAVA_OPTS="$JAVA_OPTS -Djavax.net.ssl.keyStore=<TOMCAT_HOME>/conf/wso2carbon.jks -Djavax.net.ssl.keyStorePassword=wso2carbon"
JAVA_OPTS="$JAVA_OPTS -Djavax.net.ssl.trustStore=<TOMCAT_HOME>/conf/client-truststore.jks -Djavax.net.ssl.trustStorePassword=wso2carbon"

Make sure to change the <TOMCAT_HOME> to the correct path where the external tomcat resides, to point to the keystore files of the tomcat.

4. Navigate to <TOMCAT_HOME>/webapps/authenticationendpoint/WEB-INF/classes/EndpointConfig.properties file and change the configs

client.keyStore=<TOMCAT_HOME>/conf/wso2carbon.jks
client.trustStore=<TOMCAT_HOME>/conf/client-truststore.jks

pointing to the correct location inside <TOMCAT_HOME>/conf folder.

5. Finally restart the tomcat server to deploy these changes to the authentication portal!!!

Console

Now let us see how we can build the console app in a compatible way to be deployed externally to the IS.

  1. Clone the identity-apps repo.
git clone https://github.com/wso2/identity-apps.git

Since the identity-apps repo get constantly updated with new updates, to try out this tutorial it would be better to checkout to v1.6.127 tag as it is the compatible version for IS 6.1.0-m1 pack we are using here.

git checkout v1.6.127

2. Uncomment the SERVER_TYPE variable in the apps/console/.env.local file to set the external server type as static.

SERVER_TYPE="static"

3. Change the appBaseName value from “console” to “” in apps/console/src/public/deployment.config.json file.

"appBaseName": "",

4. Open the apps/console/src/index.tsx file and do the following changes:

a. Change the following import statement

import { AuthParams, AuthProvider, SPAUtils } from "@asgardeo/auth-react";

to

import { AuthParams, AuthProvider, ResponseMode, SPAUtils } from "@asgardeo/auth-react";

b. Change the following if condition

if (!SPAUtils.hasAuthSearchParamsInURL() && process.env.NODE_ENV === "production") {

to

if (!SPAUtils.hasAuthSearchParamsInURL()
    && window[ "AppUtils" ].getConfig().idpConfigs.responseMode == ResponseMode.formPost) {

5. Open a terminal inside apps/console and build the console application.

cd apps/console
pnpm build

Make sure you have the required prerequisites to build the app locally.

After the build is successful, you can deploy the artefacts inside apps/console/build/console in a static server and use the console application externally from the IS server.

Here I will show you how you can use live-server to simply test out this app.

  1. If you do not have live-server installed, use the following command to install it locally.
npm install -g live-server

2. Open a terminal inside apps/console/build/console and run the following command to deploy the app in a live-server instance in port 8081.

live-server --port=8081

Now the console app can be accessed through http://localhost:8081.

Myaccount

You can follow the same corresponding steps mentioned above to build and deploy the myaccount application inside the identity-apps/apps/myconsole folder.

  1. Install identity-apps repo.
  2. Uncomment the SERVER_TYPE variable in the apps/myaccount/.env.local file.
  3. Change the appBaseName value from “myaccount” to “” in apps/myaccount/src/public/deployment.config.json file.
  4. Follow the relevant code changes mentioned in the console app section here as well for the myaccount app inside the apps/myaccount/src/index.tsx file.
  5. Open a terminal inside apps/myaccount and build the app.
cd apps/myaccount
pnpm build

Finally, open a terminal inside apps/myaccount/build/myaccount and run the following command to deploy the app in a live-server instance in port 8082.

live-server --port=8082

Now the myaccount app can be accessed through http://localhost:8082.

Integrating the portals with the IS server

Now we have successfully deployed the authentication portal, console and myaccount apps in 3 different external servers. Let us try out integrating these portals with the IS server and accessing them.

  1. Use the previously downloaded IS pack.
  2. Add the following configs to the $IS_HOME/repository/conf/deployment.toml and start the IS server.
[system_applications]
read_only_apps = []
[authentication.endpoints]
login_url="https://localhost:8443/authenticationendpoint/login.do"
retry_url="https://localhost:8443/authenticationendpoint/retry.do"
request_missing_claims_url="https://localhost:8443/authenticationendpoint/claims.do"[oauth.endpoints]
oauth2_consent_page= "https://localhost:8443/authenticationendpoint/oauth2_authz.do"
oauth2_error_page= "https://localhost:8443/authenticationendpoint/oauth2_error.do"
oidc_consent_page= "https://localhost:8443/authenticationendpoint/oauth2_consent.do"
oidc_logout_consent_page= "https://localhost:8443/authenticationendpoint/oauth2_logout_consent.do"
oidc_logout_page= "https://localhost:8443/authenticationendpoint/oauth2_logout.do"[saml.endpoints]
logout= "https://localhost:8443/authenticationendpoint/samlsso_logout.do"
notification= "https://localhost:8443/authenticationendpoint/samlsso_notification.do"[passive_sts.endpoints]
retry= "https://localhost:8443/authenticationendpoint/retry.do"[cors]
allow_generic_http_requests = true
allow_any_origin = false
allowed_origins = [
    "http://localhost:8080","https://localhost:9443", "http://localhost:8081", "http://localhost:8082", "https://localhost:8443"
]
allow_subdomains = true
supported_methods = [
    "GET",
    "POST",
    "HEAD",
    "OPTIONS"
]
support_any_header = true
supported_headers = []
exposed_headers = []
supports_credentials = true
max_age = 3600
tag_requests = false

2. Login to the default console app available at https://localhost:9443/console and update the callback urls of myaccount and console apps.

a. Applications → Console → Edit → Protocol → Authorized redirect URLs → Add http://localhost:8081 → Update

b. Applications → Myaccount → Edit → Protocol → Authorized redirect URLs → Add http://localhost:8082 → Update

3. Access the apps at:

Console: http://localhost:8081

Myaccount: http://localhost:8082

If you check the network tab while accessing the externally hosted myaccount/console apps, you can see that the authentication request is redirected to https://localhost:8443/authenticationendpoint instead of the default authentication endpoint https://localhost:9443/authenticationendpoint.

This way you can deploy these webapps seperately independent of the IS server and customize as required.

Happy coding!

Wso2is

--

--

Imalsha Gunasekara

Written by Imalsha Gunasekara

25 Followers

Help

Status

About

Careers

Blog

Privacy

Terms

Text to speech

Teams