Skip to content

Latest commit

Β 

History

History
856 lines (522 loc) Β· 19.7 KB

CONFIGURATION.md

File metadata and controls

856 lines (522 loc) Β· 19.7 KB

Configurations

Overview

The portals i.e. Console & My Account are configurable using the deployment.toml when they are hosted inside the Identity Server. The Jinja 2 template files which can be found in features/org.wso2.identity.apps.{$appName}.server.feature/resources/deployment.config.json.j2 are used to template the configuration file i.e. deploymemnt.config.json which can be found at the root of the webapp.

Note: If the portals are to be hosted outside, the aforementioned deployment.config.json file has to be modified accordingly.

To learn more abut the new configuration model, click here.

Common Configs

The following sections contain the common configs that are needed to configure/override the existing behaviour of the Console or My Account application.

app_base_name

βœ… Default JSON value - "console" | "myaccount"

This configuration is needed if you want to change app base name from console or myaccount to something else.

Note: Changing just the bellow config will not be enough to achieve the desired results. You will have to manually rename the application in <IS_HOME>/repository/deployment/server/webapps. And also you will have to refactor the paths(links to the theme, rpIframe etc.) in index.jsp at the root of the console webapp.

Supported Values - Any string value

[console]
app_base_name = "custom-console"

Note for Developers: If you want to build the application with a different basename, change this config in <REPO_ROOT>/apps/console/src/public/deployment.config.json. Webapack will use this value during build time to put all the build files.

app_base_name_for_history_api

πŸ’‘ No value defined in Default JSON

🏁 Fallback Value - "/"

Base name used by the browser history API. For the default SaaS behaviour / has been used due to limitations in history API. See remix-run/history#644. This config was added to enable support for none SaaS apps so that they can easily history push.

Supported Values - Any path with a leading forward slash.

[console]
app_base_name_for_history_api = "/console"

client_id

βœ… Default JSON value - "CONSOLE" | "MY_ACCOUNT"

Client ID of the application.

Supported Values - Any string value. Check the OIDC configurations section of the application to retrieve the correct value.

[console]
client_id = "CONSOLE"

debug

βœ… Default JSON value - false

Enable debug logs for certain features such as i18n etc.

Supported Values - true | false

[console]
debug.enable = true

idp_configs

Configs for the authentication SDK.

enablePKCE

πŸ’‘ No value defined in Default JSON

🏁 Fallback Value - true

The Proof Key for Code Exchange (PKCE) is a specification supported by WSO2 Identity Server to mitigate code interception attacks. See Mitigating Authorization Code Interception Attacks to configure PKCE for an OAuth application.

Supported Values - true | false

[console]
idp_configs.enablePKCE = true

clockTolerance

πŸ’‘ No value defined in Default JSON

🏁 Fallback Value - 60 Seconds (Declared in SDK)

Allowed leeway when validating the id_token. Required to address possible time mismatches between the client and the server. Check the Specification

Supported Values - Any number (in Seconds)

[console]
idp_configs.clockTolerance = 120

responseMode

πŸ’‘ No value defined in Default JSON

🏁 Fallback Value - "form_post"

How the result of the authorization request is formatted.

Supported Values - "form_post" | "query"

[console]
idp_configs.responseMode = "form_post"

scope

πŸ’‘ No value defined in Default JSON

🏁 Fallback Value - [ "SYSTEM" ]

Scopes requested when the token request is made.

Supported Values - String array

[console]
idp_configs.scope = [ "internal_login", "internal_identity_mgt_view" ]

serverOrigin

πŸ’‘ No value defined in Default JSON

🏁 Fallback Value - "https://localhost:9443"

The origin of the Identity Provider. eg: https://localhost:9443

Supported Values - Any URL.

[console]
idp_configs.serverOrigin = "https://localhost:9443"

storage

πŸ’‘ No value defined in Default JSON

🏁 Fallback Value - "webWorker"

The storage medium where the session information such as the access token should be stored.

Supported Values - "sessionStorage" | "webWorker" | "localStorage"

[console]
idp_configs.storage = "webWorker"

authorizeEndpointURL

πŸ’‘ No value defined in Default JSON

🏁 Fallback Value - "/oauth2/authorize"

The endpoint to send the authorization request to.

Supported Values - Any relative URL.

[console]
idp_configs.authorizeEndpointURL = "/oauth2/authorize"

jwksEndpointURL

πŸ’‘ No value defined in Default JSON

🏁 Fallback Value - "/oauth2/jwks"

The endpoint from which the JSON Web Keyset can be obtained.

Supported Values - Any relative URL.

[console]
idp_configs.jwksEndpointURL = "/oauth2/jwks"

logoutEndpointURL

πŸ’‘ No value defined in Default JSON

🏁 Fallback Value - "/oidc/logout"

The endpoint to send the logout request to.

Supported Values - Any relative URL.

[console]
idp_configs.logoutEndpointURL = "/oidc/checksession"

oidcSessionIFrameEndpointURL

πŸ’‘ No value defined in Default JSON

🏁 Fallback Value - "/oidc/checksession"

The URL of the OIDC session iframe.

Supported Values - Any relative URL.

[console]
idp_configs.oidcSessionIFrameEndpointURL = "/oidc/checksession"

tokenRevocationEndpointURL

πŸ’‘ No value defined in Default JSON

🏁 Fallback Value - "/oauth2/revoke"

The endpoint to send the revoke-access-token request to..

Supported Values - Any relative URL.

[console]
idp_configs.tokenRevocationEndpointURL = "/oauth2/revoke"

tokenEndpointURL

πŸ’‘ No value defined in Default JSON

🏁 Fallback Value - "/oauth2/token"

The endpoint to send the token request to.

Supported Values - Any relative URL.

[console]
idp_configs.tokenEndpointURL = "/oauth2/token"

tokenEndpointURL

πŸ’‘ No value defined in Default JSON

🏁 Fallback Value - "/oauth2/oidcdiscovery/.well-known/openid-configuration"

The endpoint to receive the OIDC endpoints from.

Supported Values - Any relative URL.

[console]
idp_configs.wellKnownEndpointURL = "/oauth2/oidcdiscovery/.well-known/openid-configuration"

session

OIDC Session management configs.

userIdleTimeOut

βœ… Default JSON value - 600

Idle session timeout interval.

Supported Values - Any numerical value. (in seconds)

[console]
session.params.userIdleTimeOut = 600

userIdleWarningTimeOut

βœ… Default JSON value - 580

When will the warning modal appear to warn about idle timeout.

Supported Values - Any numerical value. (in seconds and should be less than userIdleTimeOut)

[console]
session.params.userIdleWarningTimeOut = 580

sessionRefreshTimeOut

βœ… Default JSON value - 300

When to send the session extension request.

Supported Values - Any numerical value. (in seconds)

[console]
session.params.sessionRefreshTimeOut = 300

checkSessionInterval

βœ… Default JSON value - 3

At what interval should the app poll for session state.

Supported Values - Any numerical value. (in seconds)

[console]
session.params.checkSessionInterval = 3

tenantResolutionStrategy

πŸ’‘ No value defined in Default JSON

🏁 Fallback Value - "id_token"

How is the tenant resolved after the user is logged in. In SaaS mode, the tenant will be extracted from the logged in users ID token. Otherwise, the tenant can be obtained by reading the URL.

Supported Values - "location" | "id_token"

[console]
tenantResolutionStrategy = "id_token"

is_sass

πŸ’‘ No value defined in Default JSON

🏁 Fallback Value - true

Determines whether the app is SaaS.

Supported Values - true | false

[console]
documentation.is_sass = true

login_callback_path

βœ… Default JSON value - "/login"

Path to be redirected on login.

Supported Values - Any route determined in the app.

[console]
documentation.login_callback_path = "/login"

logout_callback_path

βœ… Default JSON value - "/login"

Path to be redirected on logout.

Supported Values - Any route determined in the app.

[console]
documentation.logout_callback_path = "/login"

server_origin

πŸ’‘ No value defined in Default JSON

🏁 Fallback Value - URL will be taken from IdentityUtil.getServerURL()

Server Origin URL to be used for API requests etc. URL will be taken from getServerURL() method in IdentityUtil when the app is deployed inside IS.

Supported Values - Any URL.

[console]
server_origin = "https://localhost:9443"

route_paths

App route paths.

home

βœ… Default JSON value - "/develop/applications" (for Console) | "/overview" (for My Account)

Where to route the users when the app is loaded.

Supported Values - Any path defined in the app.

[console]
route_paths.home = "/manage/users"

login

βœ… Default JSON value - "/login" (for Console) | "/login" (for My Account)

Where to route the users on login.

Supported Values - Any path defined in the app.

[console]
route_paths.login = "/login"

logout

βœ… Default JSON value - "/logout" (for Console) | "/logout" (for My Account)

Where to route the users on logout.

Supported Values - Any path defined in the app.

[console]
route_paths.logout = "/logout"

ui

UI configurations.

announcements

Announcements to be displayed on the banner. Configured as an array.

color

πŸ’‘ No value defined in Default JSON

Color of the Announcements banner.

Supported Values - SemanticCOLORS | "primary" | "secondary"

[[console.ui.announcements]]
color = "primary"
order

πŸ’‘ No value defined in Default JSON

Order of the Announcement.

Supported Values - number

[[console.ui.announcements]]
order = 1.0
expire

πŸ’‘ No value defined in Default JSON

Announcement expiry time.

Supported Values - Time stamp.

[[console.ui.announcements]]
expire = "1593475200"
id

πŸ’‘ No value defined in Default JSON

Unique ID for the Announcement.

Supported Values - Any string. Preferably a GUID.

[[console.ui.announcements]]
id = "d47a8201-3d58-43ae-b1a9-1ac653814f4e"
message

πŸ’‘ No value defined in Default JSON

Main message for the Announcement.

Supported Values - Any string.

[[console.ui.announcements]]
message = "Regular maintenance work will be carried out and the service will be unavailable for few hours."

app_copyright

βœ… Default JSON value - "WSO2 Identity Server"

App copyright to be displayed on footer.

Supported Values - Any string.

[console]
ui.app_copyright = "WSO2 Identity Server"

app_title

βœ… Default JSON value - "Console | WSO2 Identity Server" (for Console) | "My Account | WSO2 Identity Server" (for My Account)

Browser tab title.

Supported Values - Any string.

[console]
ui.app_title = "Console | WSO2 Identity Server"

app_name

βœ… Default JSON value - "Console" (for Console) | "My Account" (for My Account)

Display name of the app.

Supported Values - Any string.

[console]
ui.app_name = "Console"

app_logo_path

βœ… Default JSON value - "/assets/images/logo.svg"

Path of the app logo.

Supported Values - Relative paths (will be resolved from the resource bundle) | Hosted Images | Data URLs

[console]
ui.app_logo_path = "https://cdn.wso2.is.com/assets/images/logo.svg"

gravatar.configs

Gravatar configs.

fallback

βœ… Default JSON value - "404"

Fallback types for gravatar images.

Supported Values - "404" | "default" | "mp" | "identicon" | "monsterid" | "wavatar" | "retro" | "robohash" | "blank"

[console]
ui.gravatar.configs.fallback = "404"
defaultImage

πŸ’‘ No value defined in Default JSON

Custom fallback image URL if Gravatar is not found.

Supported Values - Any image URL.

[console]
ui.gravatar.configs.defaultImage = "https://cdn.wso2.is.com/assets/images/gravatar-fallback.png"
size

πŸ’‘ No value defined in Default JSON

Gravatar image size.

Supported Values - Any number. See http://en.gravatar.com/site/implement/images/#size.

[console]
ui.gravatar.configs.size = 200

product_name

βœ… Default JSON value - "Identity Server"

Product name.

Supported Values - Any string.

[console]
ui.product_name = "Identity Server"

product_version.configs

Configurations for customizing the product version label.

allowSnapshot

πŸ’‘ No value defined in Default JSON

🏁 Fallback Value - false

Shows the snapshot label if present in product version.

Supported Values - true | false

[console]
product_version.configs.allowSnapshot = false

versionOverride

πŸ’‘ No value defined in Default JSON

Overrides the version number. Use "" if version should be hidden. Drop the attribute if no change to version number is required.

Supported Values - Any string or ""

[console]
product_version.configs.versionOverride = "ALPHA"

textCase

πŸ’‘ No value defined in Default JSON

Text case for the version.

Supported Values - "lowercase" | "uppercase"

[console]
product_version.configs.textCase = "uppercase"

labelColor

πŸ’‘ No value defined in Default JSON

🏁 Fallback Value - "primary"

Color of the label.

Supported Values - "auto" | "primary" | "secondary" | SemanticCOLORS

[console]
product_version.configs.labelColor = "primary"

theme

Theme configurations.

name

βœ… Default JSON value - "default"

Name of the app theme.

Supported Values - Any string.

[console]
theme = "default"

Console Specific Configs

The following sections contain Console specific configs that cann be used to configure/override the existing behaviour of the Console application.

applications

Different configurations for applications that are used inside the Console.

account_app

My Account app configurations.

[console]
applications.account_app.configs.origin = "<MY_ACCOUNT_ORIGIN>" # Defaults to the server URL (ex: https://localhost:9443).
applications.account_app.configs.path = "<PATH>" # Relative path(without tenant) to navigate when the My Account link is clicked on the user dropdown. Defaults to `/myaccount/overview`.

admin_app

Console app's Manage section configs.

[console]
applications.admin_app.configs.basePath = "<BASE_PATH>" # Defaults to the `/manage`.
applications.admin_app.configs.displayName = "<DISPLAY_NAME>" # Name to displayed in the tab. Defaults to the `Manage`.
applications.admin_app.configs.path = "<PATH>" # Path to navigate the users when the manage tab is clicked. Defaults to the `/manage/users`.

developer_app

Console app's Develop section configs.

[console]
applications.developer_app.configs.basePath = "<BASE_PATH>" # Defaults to the `/develop`.
applications.developer_app.configs.displayName = "<DISPLAY_NAME>" # Name to displayed in the tab. Defaults to the `Develop`.
applications.developer_app.configs.path = "<PATH>" # Path to navigate the users when the manage tab is clicked. Defaults to the `/develop/applications`.

documentation

In app Documentation deployment related configurations. These will be used to display docs in applications help panel etc..

base_url

βœ… Default JSON value - "https://api.github.com"

Base URL of the hosted docs site. By default, IS docs hosted on GitHub is used, hence base URL is the GitHub API.

Supported Values - Any absolute URL.

[console]
documentation.base_url = "https://docs.wso2.is.com"

content_base_url

βœ… Default JSON value- "https://api.github.com/repos/wso2/docs-is/contents/en/docs"

Where to find docs content. By default, main content is available inside /en/docs.

Supported Values - Any absolute URL.

[console]
documentation.base_url = "https://docs.wso2.is.com/en/docs"

github_options

Extra config options if the docs are hosted on GitHub.

branch

βœ… Default JSON value - "new_restructure",

GitHub branch to look for content.

Supported Values - Any string.

[console]
documentation.github_options.branch = "main"

image_prefix_url

βœ… Default JSON value - "https://github.com/wso2/docs-is/raw/new_restructure/en/docs/"

URL to prefix to relative image paths.

Supported Values - Any URL.

[console]
documentation.image_prefix_url = "https://docs.wso2.is.com/en/docs"

provider

βœ… Default JSON value - "GITHUB"

Documentation provider.

Supported Values - "GITHUB" | "CUSTOM"

[console]
documentation.provider = "CUSTOM"

structure_file_type

βœ… Default JSON value - "YAML"

File type of the docs structure file. Currently in docs-is, a YAML file is used to maintain the structure of the repo. So in order to read the file in react context, it has to be parsed. This config will tell the code base to parse the YAML. Any other file type will be returned raw as pwe current implementation.

Supported Values - "YAML" | undefined

[console]
documentation.structure_file_type = "YAML"

structure_file_url

βœ… Default JSON value - "https://api.github.com/repos/wso2/docs-is/contents/en/mkdocs.yml"

URL for the structure file.

Supported Values - Any absolute URL.

[console]
documentation.structure_file_url = "https://docs.wso2.is.com/en/mkdocs.yml"

extensions

❎ No value defined in Default JSON

App extensions configuration.