Configuring SSO in DS

SSO (Single Sign-on) allows a user to enter one username and password to access multiple applications. Thereby, a user can use a preferred Identity Server to log into the WSO2 Dashboard Server (WSO2 DS). WSO2 Identity Server features have been embedded in the WSO2 Dashboard Server. Therefore, if you want, you can use the WSO2 Dashboard Server as your Identity Server. Otherwise, you can use an external Identity Server as the identity server provider. For more information on SSO, see Single Sign-on.

Enabling SSO in WSO2 DS

In the following steps, it is assumed that you have already started the following servers:

WSO2 Dashboard Server
WSO2 Identity Server - This is only required if you are using WSO2 IS as the external identity provider.

Step 1 - Configure the WSO2 DS portal app

Open the <DS_HOME>/repository/deployment/server/jaggeryapps/portal/configs/designer.json file.

Click here to view a sample designer.json...

{
  "store": {
    "type": "fs"
  },
  "authentication": {
    "activeMethod": "sso",
    "methods": {
      "sso": {
        "attributes": {
          "issuer": "portal",
          "identityProviderURL": "https://localhost:9443/samlsso",
          "responseSigningEnabled": "false",
          "acs": "https://localhost:9443/portal/acs",
          "identityAlias": "wso2carbon",
          "useTenantKey": false
        }
      },
      "basic": {
        "attributes": {}
      }
    }
  },
  "designers": [
    "Internal/everyone"
  ],
  "tenantPrefix": "/t",
  "shareStore": false,
  "theme": "basic",
  "cacheTimeoutSeconds": "5",
  "cacheSizeBytes": "1073741824",
  "defaultDashboardRedirect": false,
  "isCreateGadgetEnable": false,
  "oauth": {
    "username": "admin",
    "password": "admin"
  }
}

Enable SSO by setting the activeMethod property, which is in the authentication section, to sso.
```
"activeMethod": "sso",
```

Provide the following details.

Property	Description	Sample Value
`identityProviderURL`	Enter a valid external or internal Identity Server URL. This URL is used to validate the destination of the SAML request. The Identity Server compares the value of the "destination", which is inside the SAML request, with the URL that corresponds to this property. The Identity Server does this to ensure that the application communicates with the correct identity provider. The identity provider URL should have the following format: `https://<HOSTNAME>:<PORT>/samlsso`	`https://localhost:9443/samlsso`
`acs`	Enter the assertion consumer service (ACS) URL of the service provider. This defines the URL that the browser is redirected to after the authentication is successful. The identity provider redirects the SAML2 response to this ACS URL. However, if the SAML2 request is signed, and the SAML2 request contains the ACS URL, the Identity Server honors the ACS URL of the SAML2 request. The ACS URL should have the following format: `https://<HOSTNAME>:<PORT>/acs`	`https://localhost:9443/portal/acs`
`issuer`	Enter the name of the SAML SSO service provider here, because the SAML SSO service provider acts as the issuer, distributing tokens. This value is used as a unique identifier for the service provider. This can contain any string, which is unique.	portal
`responseSigningEnabled`	This is used to sign the SAML2 responses returned after the authentication process is complete. If you want response signing to take place, set this property to "true". Make sure to enable the same property when registering the portal application in the Identity Server.	true
identityAlias	This is used to validate the digital signature, which is used to sign all SAML assertions, requests, and responses.
`useTenantKey`	If you want to enable tenant users to log into the portal app, set this value to `true`.	false

Step 2 - Register the portal app with the Identity Server

You need to create a service provider, to register the portal app with the Identity Server. However, the steps involved changes based on the Identity Server being used.

Skip this step if you are using an external Identity Server other than the built-in WSO2 Identity Server.

Follow the instructions below only if you are using the internal Identity Server, which is embedded within WSO2 DS, or if you are using the external WSO2 Identity Server:

Possible Error

When trying to access the Dashboard Designer or a dashboard, without creating a service provider and only configuring the portal app for SSO, the following errors appear:

Disabling SSO in WSO2 DS

By default, SSO is disabled in WSO2 DS. However, if SSO has been enabled previously, you can follow the steps below to disable SSO in WSO2 DS:

In the following steps, it is assumed that you have already started the WSO2 Dashboard Server.

Open the <DS_HOME>/repository/deployment/server/jaggeryapps/portal/configs/designer.json file.
Disable SSO by setting the activeMethod, which is in the authentication section, to basic.
```
"activeMethod": "basic",
```