WSO2 Identity Server Apps

End-user apps in WSO2 Identity Server

---

Table of Content

• Prerequisite
  • Setup Development Environment
  • Download WSO2 Identity Server
  • Setup WSO2 Identity Server
    • Allow CORS Origins
    • Configure FIDO2 origins
    • Make Applications Editable
    • Configure Callback URLs for System Applications (for WSO2 IS v7.0 and above)
    • Start the Identity Server
    • Configure Callback URLs for System Applications (for WSO2 IS below v7.0)
• Build & Run
  • Build
    • For Console & My Account
    • For JSP apps (authentication portal, recovery portal, etc)
  • Run
    • Console
    • My Account
• Releases
• Configuration
• Deployment
• Connectors
• Troubleshoot
• Contributing
• Reporting Issues
• License

Prerequisite

Setup Development Environment

1. Install NodeJS LTS(Latest Stable Version) from https://nodejs.org/en/download/.
2. Install pnpm.

Note: Only PNPM v9 and above are supported.

```shell
corepack prepare pnpm@latest --activate
```

Or, follow the other [recommended installation options](https://pnpm.io/installation).

3. Install Maven from https://maven.apache.org/download.cgi.
4. Install JDK 11 https://openjdk.org/projects/jdk/.
5. Install the recommended developer tools.

Download WSO2 Identity Server

In order to setup this repository locally, you need to have WSO2 Identity Server installed on your local environment.

We recommend you to download the latest release or build the product-is from source.

Setup WSO2 Identity Server

Allow CORS Origins

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

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

Configure FIDO2 origins

Add your hostname and port as a trusted FIDO2 origin to the deployment.toml file as given below.

[fido.trusted]
origins=["https://localhost:9000"]

Make Applications Editable

Currently, Console & My Account are considered as system applications hence they are readonly by default. In order to configure them, you need to add the following config to the deployment.toml file to override the default behavior.

[system_applications]
read_only_apps = []

Configure Callback URLs for System Applications (for WSO2 IS v7.0 and above)

Important

In Identity Server v7.0 and above, callback_urls for system applications need to be configured from the deployment.toml file. If your Identity Server version is below v7.0, callback URLs can be configured from the developer console, which is explained in a later step in this guide.

[console]
callback_url = "regexp=(https://localhost:9443/console|https://localhost:9443/t/(.*)/console|https://localhost:9443/console/login|https://localhost:9443/t/(.*)/console/login|https://localhost:9001/console|https://localhost:9001/t/(.*)/console|https://localhost:9001/console/login|https://localhost:9001/t/(.*)/console/login|https://localhost:9443/o/(.*)/console|https://localhost:9001/o/(.*)/console|https://localhost:9001/o/(.*)/console/login)"

[myaccount]
callback_url = "regexp=(https://localhost:9443/myaccount|https://localhost:9443/t/(.*)/myaccount|https://localhost:9443/myaccount/login|https://localhost:9443/t/(.*)/myaccount/login|https://localhost:9000/myaccount|https://localhost:9000/t/(.*)/myaccount|https://localhost:9000/myaccount/login|https://localhost:9000/t/(.*)/myaccount/login)"

Start the Identity Server

Now you can go ahead and start WSO2 Identity Server that was downloaded in the Prerequisites step.

For instructions on startup, read the docs.

Configure Callback URLs for System Applications (for WSO2 IS below v7.0)

ℹ️ Note

This step is only applicable for WSO2 Identity Server versions below v7.0.

1. Navigate to the Management Console i.e https://localhost:9443/carbon/ from the browser, and login to the system by entering an admin password.

💡 Find out the default password details at https://docs.wso2.com/display/ADMIN44x/Configuring+the+System+Administrator

2. In the Management Console,

   • navigate to Service Providers -> List from left side panel.

   • Then go to Edit option in the application that you want to configure in dev mode (ex: MY_ACCOUNT).

   • Click on Inbound Authentication Configuration -> OAuth/OpenID Connect Configuration -> Edit.

   • Update the Callback Url field with below corresponding values.

     • Console

       regexp=(https://localhost:9443/console|https://localhost:9443/t/(.*)/console|https://localhost:9443/console/login|https://localhost:9443/t/(.*)/console/login|https://localhost:9001/console|https://localhost:9001/t/(.*)/console|https://localhost:9001/console/login|https://localhost:9001/t/(.*)/console/login|https://localhost:9443/o/(.*)/console|https://localhost:9001/o/(.*)/console|https://localhost:9001/o/(.*)/console/login)

     • My Account

       regexp=(https://localhost:9443/myaccount|https://localhost:9443/t/(.*)/myaccount|https://localhost:9443/myaccount/login|https://localhost:9443/t/(.*)/myaccount/login|https://localhost:9000/myaccount|https://localhost:9000/t/(.*)/myaccount|https://localhost:9000/myaccount/login|https://localhost:9000/t/(.*)/myaccount/login)

Build & Run

Build

Clone or download the identity-apps repository 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.

For Console & My Account

# From project root.
pnpm install && pnpm build

For JSP apps (authentication portal, recovery portal, etc)

# From project root.
cd identity-apps-core

mvn clean install

Run

To start the apps in development mode, execute the following commands accordingly.

Console

# To start Console
cd apps/console
pnpm start

Once the development server is up and running, you can access the application via https://localhost:9001/console.

My Account

# To start My Account
cd apps/myaccount
pnpm start

Once the development server is up and running, you can access the application via https://localhost:9000/myaccount.

Releases

This repository uses 🦋 Changesets to manage releases. Refer to release documentation to learn more about the release process.

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

Go through our deployment guide to learn the supported app deployment options.

Connectors

Go through our connectors guide to learn how to handle connectors in the Identity Server Console.

Troubleshoot

Go through our troubleshooting guide to clarify any issues you encounter.

If the issue you are facing is not on the existing guide, consider reaching out to us on Discord, StackOverflow or by creating an issue as described in Reporting Issues.

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:

Please be advised that security issues must be reported to [email protected], 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.

---

(c) Copyright 2022 WSO2 LLC.