WSO2 Identity Server Apps

End-user apps in WSO2 Identity Server

Branch	Build Status	Travis CI Status
master

Setup build environment

Install NodeJS from https://nodejs.org/en/download/.
Install Maven from https://maven.apache.org/download.cgi. * For Maven 3.8 and up, please check the Troubleshoot section.
Install JDK 1.8 https://www.oracle.com/java/technologies/javase/javase-jdk8-downloads.html.

Build & Run

Build

Download or clone the project source code from https://github.com/wso2/identity-apps
Run mvn clean install from the command line in the project root directory (where the root pom.xml is located).

If you are building product-is, the built identity apps dependencies will install to your local .m2 repository during the build above.

Then you just need to build WSO2 Identity Server after. (Follow the guide there)

Run

Execute wso2server.sh (For unix environment) or wso2server.bat (For windows environment) file from the bin directory to run the WSO2 Identity Server.
Navigate to https://localhost:9443/myaccount or https://localhost:9443/console from the browser. (Add certificate exception if required)

Run in dev mode

Do only if you skip WSO2 Identity Server build step above: Download the built distribution of WSO2 Identity Server from https://wso2.com/identity-and-access-management/.

Add the following code to repository/conf/deployment.toml in WSO2 Identity Server distribution pack to allow CORS.

[cors]
allowed_origins = [
   "https://localhost:9000",
   "https://localhost:9001"
]
supported_methods = [
   "GET",
   "POST",
   "HEAD",
   "OPTIONS",
   "PUT",
   "PATCH",
   "HEAD",
   "DELETE",
   "PATCH"
]
exposed_headers = [ "Location" ]

Add your hostname and port as a trusted FIDO2 origin to the deployment.toml file as given below.
```
 [fido.trusted]
 origins=["https://localhost:9000"]
```
Currently, Console & My Account are considered as system applications hence they are readonly by default. So in order to configure the Callback Urls as specified in step 7, you need to add the following config to the deployment.toml file to override the default behaviour.
```
[system_applications]
read_only_apps = []
```
Execute wso2server.sh (For unix environment) or wso2server.bat (For windows environment) file from the bin directory to run WSO2 Identity Server.
Navigate to https://localhost:9443/carbon/ from the browser, and login to the system by entering an admin password.

Hint! Can find out the default password details here: https://docs.wso2.com/display/ADMIN44x/Configuring+the+System+Administrator

In the system, navigate to Service Providers -> List from left side panel. And then go to Edit option in the application that you want to configure in dev mode (ex: MY_ACCOUNT). Then click on Inbound Authentication Configuration -> OAuth/OpenID Connect Configuration -> Edit. And then update the Callback Url field with below corresponding values.

My Account

regexp=(https://localhost:9443/myaccount/login|https://localhost:9443/myaccount/logout|https://localhost:9000/myaccount/login|https://localhost:9000/myaccount/logout|https://localhost:9000/myaccount)

Console

regexp=(https://localhost:9443/console/login|https://localhost:9443/console/logout|https://localhost:9001/console/login|https://localhost:9001/console/logout|https://localhost:9001/console)

Open cloned or downloaded Identity Apps repo and run the following commands from the command line in the project root directory (where the package.json is located) to build all the packages with dependencies. (Note:- Not necessary if you have already done above identity apps build steps)
```
# `npm run bootstrap` will install npm dependencies and bootstrap lerna modules.
npm run bootstrap && npm run build
```
or
```
# This will run `npm run bootstrap && npm run build` in the background.
npm run build:dev
```
Note:-

To build a single package/app, you can use this command: npx lerna bootstrap --scope <package-name> && npx lerna run --scope <package-name> build.

E.g. npx lerna bootstrap --scope @wso2is/myaccount && npx lerna run --scope @wso2is/myaccount build
Start the apps in development mode, Execute cd apps/<app> && npm start command. E.g. cd apps/myaccount && npm start.
Once the app is successfully started, you can access the via the URLs https://localhost:9000/myaccount or https://localhost:9001/console.

Running Tests

Unit Tests

Product Unit tests have been implemented using Jest along with React Testing Library and you can run the unit test suites using the following commands.

Run Tests for all modules

npm run test

Run Tests for individual module

npx lerna run test --scope @wso2is/forms

Integration Tests

Product integration tests have been written using Cypress Testing Framework and you can run the test suites using the following command.

Headless mode

npm run test:integration

Interactive mode

npm run test:integration:interactive

Only Smoke Tests

npm run test:integration:smoke

For more information regarding the test module, checkout the README in the tests module.

Configuration

The portals i.e. Console & My Account are configurable using the deployment.toml when they are hosted inside the Identity Server. Read through our configurations guidelines to learn about the configuration process.

Deployment

Deploying the apps on an external server

It is possible to deploy the Console and My Account applications on an external server. To do so, the following steps has to be followed in order to build the applications.

Method 1 - Build using Maven

Follow the steps in listed here in-order to build the project with maven.

Once the build is complete, execute the following commands in-order to build the Console & My Account applications for external deployment.

Console

Deploy on a Java EE server (ex: Tomcat)

npx lerna run build:external --scope @wso2is/console

Deploy on a static server.

npx lerna run build:external:static --scope @wso2is/console

Once the build is completed, you can find the build artifacts inside the build folder i.e apps/console/build.

My Account

Deploy on a Java EE server (ex: Tomcat)

npx lerna run build:external --scope @wso2is/myaccount

Deploy on a static server.

npx lerna run build:external:static --scope @wso2is/myaccount

Once the build is completed, you can find the build artifacts inside the build folder i.e apps/myaccount/build.

Method 2 - Build using npm

You can simply use npm to build the Console and My Account applications for external deployment by just executing the following script.

Deploy on a Java EE server (ex: Tomcat)

# From project root
npm run build:external

Deploy on a static server.

# From project root
npm run build:external:static

The respective build artifacts could be found inside the build folder. (apps/(myaccount|console)/build)

Troubleshoot

If you face any out of memory build failures, make sure that you have set maven options to set MAVEN_OPTS=-Xmx384M

For Maven v3.8 up, add below configuration to the ~/.m2/settings.xml (Create a new file if the file exist)

<settings>
  <mirrors>
    <mirror>
      <id>wso2-nexus-public</id>
      <mirrorOf>external:http:*</mirrorOf>
      <url>http://maven.wso2.org/nexus/content/groups/wso2-public/</url>
      <blocked>false</blocked>
    </mirror>
    <mirror>
      <id>wso2-nexus-release</id>
      <mirrorOf>external:http:*</mirrorOf>
      <url>http://maven.wso2.org/nexus/content/repositories/releases/</url>
      <blocked>false</blocked>
    </mirror>
    <mirror>
      <id>wso2-nexus-snapshots</id>
      <mirrorOf>external:http:*</mirrorOf>
      <url>http://maven.wso2.org/nexus/content/repositories/snapshots/</url>
      <blocked>false</blocked>
    </mirror>
  </mirrors>
</settings>

Contributing

Go through our contributing guideline to get an understanding about our contribution process and other necessary instructions.

Reporting Issues

We encourage you to report issues, improvements and feature requests regarding the project through GitHub Issue Tracker.

Important: And please be advised that, security issues must be reported to security@wso2.com, not as GitHub issues, in order to reach proper audience. We strongly advise following the WSO2 Security Vulnerability Reporting Guidelines when reporting the security issues.

License

Licenses this source under the Apache License, Version 2.0 (LICENSE), You may not use this file except in compliance with the License.

sahandilshan/identity-apps

WSO2 Identity Server Apps

Setup build environment

Build & Run

Build

Run

Run in dev mode

Running Tests

Unit Tests

Run Tests for all modules

Run Tests for individual module

Integration Tests

Headless mode

Interactive mode

Only Smoke Tests

Configuration

Deployment

Deploying the apps on an external server

Method 1 - Build using Maven

Deploy on a Java EE server (ex: Tomcat)

Deploy on a static server.

Deploy on a Java EE server (ex: Tomcat)

Deploy on a static server.

Method 2 - Build using npm

Deploy on a Java EE server (ex: Tomcat)

Deploy on a static server.

Troubleshoot

Contributing

Reporting Issues

License