WSO2 Identity Server: Enterprise Deployment and Hardening Guide

Overview

WSO2 Identity Server is an enterprise identity and access management platform used to centralize authentication, authorization, federation, and user lifecycle services. Organizations adopt it to implement single sign-on, multi-factor authentication, OAuth 2.0/OpenID Connect, SAML 2.0, SCIM provisioning, and adaptive authentication across internal, customer, and partner applications.

Enterprises choose WSO2 Identity Server when they need strong protocol support, on-premises or hybrid deployment flexibility, and deep customization. It is especially useful in regulated environments where identity flows, user stores, and audit controls must remain under organizational control.

Architecture

A typical WSO2 Identity Server deployment includes these core components:

• Authentication framework for local and federated login flows
• User stores such as LDAP, Active Directory, or JDBC-backed repositories
• Identity providers for federation with Microsoft Entra ID, Google, or social login providers
• Service providers representing enterprise applications
• Token and session services for OAuth 2.0, OIDC, SAML, and session management
• Databases for identity, consent, session, and shared configuration data

Deployment models

• Single node: suitable for development and small internal use cases
• Active-active cluster: recommended for production with a load balancer and shared databases
• Kubernetes deployment: preferred for cloud-native operations and rolling updates
• Hybrid IAM: local WSO2 with external federation to SaaS identity providers

Data flow

1. A user requests an enterprise application.
2. The application redirects to WSO2 Identity Server using OIDC or SAML.
3. WSO2 validates policy, prompts for MFA if needed, and authenticates against the configured user store or external IdP.
4. WSO2 issues an ID token, access token, or SAML assertion.
5. The application validates the response and grants access.

Implementation Guide

1. Install and extract

wget https://github.com/wso2/product-is/releases/download/v7.0.0/wso2is-7.0.0.zip
unzip wso2is-7.0.0.zip -d /opt/
export WSO2_HOME=/opt/wso2is-7.0.0

2. Configure the primary database

Edit repository/conf/deployment.toml:

[server]
hostname = "is.example.com"
node_ip = "10.0.10.21"
base_path = "https://is.example.com"

[database.identity_db]
type = "postgres"
url = "jdbc:postgresql://pg01.example.com:5432/wso2_identity"
username = "wso2is"
password = "$env{ID_DB_PASSWORD}"
driver = "org.postgresql.Driver"

[user_store]
type = "database_unique_id"

[keystore.primary]
file_name = "repository/resources/security/wso2carbon.jks"
password = "$env{KS_PASSWORD}"
alias = "wso2carbon"
key_password = "$env{KEY_PASSWORD}"

3. Start the server

export ID_DB_PASSWORD='StrongDbPass!'
export KS_PASSWORD='ChangeThisNow!'
export KEY_PASSWORD='ChangeThisNow!'
cd $WSO2_HOME/bin
./wso2server.sh

4. Create a service provider and OIDC application

Use the management console to create an application, enable OpenID Connect, and set the callback URL to https://app.example.com/callback. Then assign claim mappings and authentication steps.

5. Configure reverse proxy

Place NGINX in front of the cluster and preserve headers:

sudo tee /etc/nginx/conf.d/wso2is.conf >/dev/null <<'EOF'
server {
  listen 443 ssl;
  server_name is.example.com;
  location / {
    proxy_pass https://10.0.10.21:9443;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Proto https;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
  }
}
EOF
sudo nginx -t && sudo systemctl reload nginx

Code Examples

Example 1: OIDC token request

curl -k -X POST https://is.example.com/oauth2/token \
  -u client_id:client_secret \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=password&username=alice&password=S3curePass!&scope=openid profile email'

Example 2: Kubernetes values snippet

wso2:
  deployment:
    replicas: 2
  ingress:
    hostname: is.example.com
  externalDatabase:
    host: pg01.example.com
    port: 5432
    database: wso2_identity
    username: wso2is
  resources:
    requests:
      cpu: "1"
      memory: "2Gi"
    limits:
      cpu: "2"
      memory: "4Gi"

Example 3: Validate OIDC discovery in Python

import requests
url = "https://is.example.com/oauth2/oidcdiscovery/.well-known/openid-configuration"
r = requests.get(url, timeout=10)
r.raise_for_status()
print(r.json()["issuer"])

Security Hardening

• Replace default keystores and rotate certificates before production go-live.
• Store secrets in environment variables or a vault, not directly in deployment.toml.
• Enforce MFA for administrators and privileged application flows.
• Restrict management console access with network ACLs and role-based access control.
• Enable TLS 1.2+ only at the reverse proxy and backend connectors.
• Use separate databases for identity data and ensure encryption at rest on database volumes.
• Forward audit logs to a SIEM and retain authentication events for compliance.
• Disable unused protocols and inbound authenticators to reduce attack surface.

Comparison

Troubleshooting

1. Database connectivity failure

Log sample:

ERROR {org.wso2.carbon.ndatasource.core.DataSourceManager} - Error in getting data source instance: jdbc/WSO2CarbonDB
org.postgresql.util.PSQLException: FATAL: password authentication failed for user "wso2is"

Fix: verify database credentials, JDBC URL, and that the PostgreSQL user has access from the WSO2 node.

2. Invalid redirect URI during OIDC login

Log sample:

WARN {org.wso2.carbon.identity.oauth.endpoint.authz.OAuth2AuthzEndpoint} - Invalid redirect_uri in the authorization request from client_id: enterprise-portal

Fix: ensure the exact callback URL is registered in the service provider, including scheme, host, path, and trailing slash behavior.

3. Certificate or hostname mismatch behind proxy

Log sample:

ERROR {org.apache.http.conn.ssl.SSLConnectionSocketFactory} - Host name 'is.example.com' does not match the certificate subject provided by the peer

Fix: install a certificate with the correct SAN entries and set hostname and proxy headers consistently.

Best Practices

Do

• Use active-active nodes with health checks and shared databases.
• Integrate with enterprise LDAP or AD for workforce identities.
• Define separate applications for dev, test, and prod to avoid token leakage.
• Monitor JVM heap, authentication latency, DB pool saturation, and token issuance rates.

Don't

• Do not expose the management console to the public internet.
• Do not keep default keystore passwords or bundled certificates.
• Do not mix administrative and customer identities in the same role model without clear separation.
• Do not enable unnecessary grant types such as password grant unless there is a documented exception.