identity-server

A Helm chart for WSO2 Identity server. This Helm chart can be used to deploy highly available and scalable WSO2 identity server deployment.

From this Helm chart, WSO2 Identity server pods are deployed and exposed through Kubernetes ingress resource. Also in advanced setup, you can configure, Kubernetes persistence volume for sharing runtime artifacts, Kubernetes secret provider class for securing secrets, Kubernetes horizontal pod autoscaling(HPA) and Kubernetes pod disruption budget(PDB). Additionally, pod affinity is configured to increase the high availability.

Required permission

User or service principle who installs the Helm chart, needs to possess actions "create", "get", "list", "update", "delete" on following K8s kinds,

Quick Start Guide

Prerequisites

• Kubernetes ingress controller. Default integration is Kubernetes Nginx ingress controller.

• An active WSO2 Subscription.

1. Add the WSO2 Helm chart repository.

helm repo add wso2 https://helm.wso2.com && helm repo update

2. Set up environment variables

export NAMESPACE=<Kubernetes Namespace to which you desire to deploy the Kubernetes resources>
export RELEASE_NAME=<Helm relase name for the deployment>
export WSO2_USERNAME=<WSO2 subscription account username>
export WSO2_PASSWORD=<WSO2 subscription account password>

3. Create Kubernetes namespace

kubectl get namespace ${NAMESPACE} || kubectl create namespace ${NAMESPACE}

4. Install Helm chart from Helm repository

 helm install "$RELEASE_NAME" wso2/identity-server --version 7.0.0-1 -n "${NAMESPACE}" \
 --set wso2.subscription.username="$WSO2_USERNAME" \
 --set wso2.subscription.password="$WSO2_PASSWORD"

Install Chart From Source

In the context of this document,

• KUBERNETES_HOME will refer to a local copy of the wso2/kubernetes-is Git repository.
  

Clone the Helm Resources for WSO2 Identity Server Git repository.

git clone https://github.com/wso2/kubernetes-is.git

 helm install "$RELEASE_NAME" -n "${NAMESPACE}" . \
 --set wso2.subscription.username="$WSO2_USERNAME" \
 --set wso2.subscription.password="$WSO2_PASSWORD"

5. Obtain the external IP

Obtain the external IP (EXTERNAL-IP) of the Identity Server Ingress resource, by listing down the Kubernetes Ingresses.

kubectl get ing -n "$NAMESPACE"

The output under the relevant column stands for the following.

• NAME: Metadata name of the Kubernetes Ingress resource
• HOSTS: Hostname of the WSO2 Identity service
• ADDRESS: External IP (EXTERNAL-IP) exposing the Identity service to outside of the Kubernetes environment
• PORTS: Externally exposed service ports of the Identity service

6. Add a DNS record mapping the hostname and the external IP

If the defined hostname (in the previous step) is backed by a DNS service, add a DNS record mapping the hostname and the external IP (EXTERNAL-IP) in the relevant DNS service.

If the defined hostname is not backed by a DNS service, for the purpose of evaluation you may add an entry mapping the hostname and the external IP in the /etc/hosts file at the client-side.

<EXTERNAL-IP> <deployment.ingress.hostName>

4. Access Management Console, Console and My Account

• Identity Server's Carbon Management Console: https://<deployment.ingress.hostName>/carbon
• Identity Server's Console: https://<deployment.ingress.hostName>/console
• Identity Server's My Account: https://<deployment.ingress.hostName>/myaccount

Advance setup

Install Helm chart on Azure Kubernetes service(AKS)

Prerequisites

• Azure Kubernetes Service(AKS) with ACR integration.
• Kubernetes ingress controller. Default integration is Kubernetes Nginx ingress controller.
• Secrets Store CSI Driver and secrets-store-csi-driver-provider-azure to integrate secure vault.
• If artifact persistence is enabled; Azure Storage account to cater persistence volume type ReadWriteMany access mode and a share is-share under the Azure storage account.
• Azure Key Vault to integrate secure vault.
• Pre-configured RDBMS. Please refer to documentation on setting up databases. In the following guide uses Azure MSQL database server.
• Azure container registry where the identity server Docker image is hosted.

To set up the infrastructure layer you can use WSO2 Terraform modules

1. Create Kubernetes namespace

export NAMESPACE=<NAMESPACE>

kubectl get namespace ${NAMESPACE} || kubectl create namespace ${NAMESPACE}

3. Create a Kubernetes TLS secret for SSL termination at ingress controller. For this you need possess the SSL certificate and the key,

kubectl create secret tls is-tls \
--cert=path/to/cert/file \
--key=path/to/key/file \
-n ${NAMESPACE}

4. Create a Kubernetes secret for keystore files. It is required to have four Java keystore files for the deployment. Please refer to the documentation for more details and how to create key stores.

   • Internal keystore(internal.jks): The key store which is used for encrypting/decrypting internal data
   • Primary keystore(primary.jks): Certificates used for signing messages that are communicated with external parties(such SAML, OIDC id_token signing)
   • TLS keystore(tls.jks): The key store which is used for tls communication.
   • Client truststore(client-truststore.jks): Certificates of trusted third parties

kubectl create secret generic keystores \
--from-file=internal.jks \
--from-file=primary.jks \
--from-file=tls.jks \
--from-file=client-truststore.jks \
-n ${NAMESPACE}

5. Create Azure storage account secret for persistence volume.

   Replace <AZURE_STORAGE_NAME> with Azure storage account name and <AZURE_STORAGE_KEY> with Azure storage account access key.

export AZURE_STORAGE_NAME='<AZURE_STORAGE_NAME>'
export AZURE_STORAGE_KEY='<AZURE_STORAGE_KEY>'

kubectl create secret generic azure-storage-csi \
--from-literal=azurestorageaccountname="${AZURE_STORAGE_NAME}" \
--from-literal=azurestorageaccountkey="${AZURE_STORAGE_KEY}" \
-n ${NAMESPACE}

6. Configure Azure key vault

   • Add internal.jks keystore password as the secret with the name INTERNAL-KEYSTORE-PASSWORD-DECRYPTED. Replace <AZURE_KEY_VAULT_NAME> with Azure Key vault name, <AZURE_SUBSCRIPTION_ID> with Azure subscription ID and <INTERNAL_KEYSTORE_PASSWORD_DECRYPTED> with internal keystore(internal.jks) password.

     export AZURE_KEY_VAULT_NAME='<AZURE_KEY_VAULT_NAME>'
     export AZURE_SUBSCRIPTION_ID='<AZURE_SUBSCRIPTION_ID>'
     export INTERNAL_KEYSTORE_PASSWORD_DECRYPTED='<INTERNAL_KEYSTORE_PASSWORD_DECRYPTED>'

     az login
     az account set -s "${AZURE_SUBSCRIPTION_ID}"
     az keyvault secret set --vault-name "${AZURE_KEY_VAULT_NAME}" --name "INTERNAL-KEYSTORE-PASSWORD-DECRYPTED" --value "${INTERNAL_KEYSTORE_PASSWORD_DECRYPTED}"

   • Create a Kubernetes secret to hold service principal credentials to access keyvault for secrets-store-csi-driver-provider-azure.

     Replace <AZURE_KEY_VAULT_SP_APP_ID> with Azure active directory service principle application ID and <AZURE_KEY_VAULT_SP_APP_SECRET> with Azure active directory service principle application secret

     export AZURE_KEY_VAULT_SP_APP_ID='<AZURE_KEY_VAULT_SP_APP_ID>'
     export AZURE_KEY_VAULT_SP_APP_SECRET='<AZURE_KEY_VAULT_SP_APP_SECRET>'

     kubectl create secret generic azure-kv-secret-store-sp \
     --from-literal=clientid="${AZURE_KEY_VAULT_SP_APP_ID}" \
     --from-literal=clientsecret="${AZURE_KEY_VAULT_SP_APP_SECRET}" \
     -n ${NAMESPACE}

7. Encrypt secrets using WSO2 secure vault encryption

   Following set of secure vault encrypted secrets are required for the deployment, please follow the guideline to encrypt secrets using WSO2 secure vault encryption. Make sure to use previously created internal.jks keystore for the WSO2 secure vault encryption.

export DATABASE_IDENTITY_ENCRYPTED_USER='<Identity database encrypted username >'
export DATABASE_IDENTITY_ENCRYPTED_PASSWORD='<Identity database encrypted user password >'
export DATABASE_SHARED_ENCRYPTED_USER='<Shared database encrypted username>'
export DATABASE_SHARED_ENCRYPTED_PASSWORD='<Shared database encrypted user password>'
export DATABASE_USER_ENCRYPTED_USER='<User database encrypted username>'
export DATABASE_USER_ENCRYPTED_PASSWORD='<User database encrypted user password>'
export DATABASE_CONSENT_ENCRYPTED_USER='<Consent database encrypted username>'
export DATABASE_CONSENT_ENCRYPTED_PASSWORD='<Consent database encrypted user password>'
export KEYSTORE_INTERNAL_ENCRYPTED_PASSWORD='<Internal key store encrypted password>'
export KEYSTORE_INTERNAL_ENCRYPTED_KEY_PASSWORD='<Internal key store key encrypted password>'
export KEYSTORE_PRIMARY_ENCRYPTED_PASSWORD='<Primary key store encrypted password>'
export KEYSTORE_PRIMARY_ENCRYPTED_KEY_PASSWORD='<Primary key store key encrypted password>'
export KEYSTORE_TLS_ENCRYPTED_PASSWORD='<TLS key store encrypted password>'
export KEYSTORE_TLS_ENCRYPTED_KEY_PASSWORD='<TLS key store key encrypted password>'
export SUPER_ADMIN_ENCRYPTED_USERNAME='<Super admin user encrypted username>'
export SUPER_ADMIN_ENCRYPTED_PASSWORD='<Super admin user encrypted password>'
export TRUSTSTORE_ENCRYPTED_PASSWORD='<Client truststore encrypted password>'
export IDENTITY_AUTH_FRAMEWORK_ENDPOINT_ENCRYPTED_APP_PASSWORD='<Encrypted app password>'
export SYMMETRIC_ENCRYPTED_KEY='<Encrypted symmetric key>'

8. Install Helm chart

Add the WSO2 Helm chart repository.

helm repo add wso2 https://helm.wso2.com && helm repo update

Replace <> places holders with values as below,

• : Azure container register(ACR) hostname
• : Azure container register(ACR) identity server image repository name
• : Azure container register(ACR) identity server image digest
• : Azure tenant ID of Azure Key vault
• : Azure Key vault name
• : Azure resource group name of Key vault
• : Azure application ID created under step 6
• : Identity database JDBC URL
• : Shared database JDBC URL
• : User database JDBC URL
• : Consent database JDBC URL
• : Identity server public hostname
• : Hash value of app password
• : Azure subscription ID

• : Helm release name for the deployment

  export IMAGE_REGISTRY_HOSTNAME='<IMAGE_REGISTRY_HOSTNAME>'
  export IMAGE_REPOSITORY_NAME='<IMAGE_REPOSITORY_NAME>'
  export IMAGE_DIGEST='<IMAGE_DIGEST>'
  export AZURE_TENANT_ID='<AZURE_TENANT_ID>'
  export AZURE_KEY_VAULT_NAME='<AZURE_KEY_VAULT_NAME>'
  export AZURE_KEY_VAULT_RG='<AZURE_KEY_VAULT_RG>'
  export AZURE_KEY_VAULT_SP_APP_ID='<AZURE_KEY_VAULT_SP_APP_ID>'
  export DATABASE_IDENTITY_URL='<DATABASE_IDENTITY_URL>'
  export DATABASE_SHARED_URL='<DATABASE_SHARED_URL>'
  export DATABASE_USER_URL='<DATABASE_USER_URL>'
  export DATABASE_CONSENT_URL='<DATABASE_CONSENT_URL>'
  export IS_HOSTNAME='<IS_HOSTNAME>'
  export ACCOUNT_RECOVERY_ENDPOINT_AUTH_HASH='<ACCOUNT_RECOVERY_ENDPOINT_AUTH_HASH>'
  export NAMESPACE='<NAMESPACE>'
  export AZURE_SUBSCRIPTION_ID='<AZURE_SUBSCRIPTION_ID>'
  export RELEASE_NAME='<RELEASE_NAME>'

helm install "$RELEASE_NAME" wso2/identity-server --version 7.0.0-1  -n "${NAMESPACE}" \
--set deployment.image.registry="${IMAGE_REGISTRY_HOSTNAME}" \
--set deployment.image.repository="${IMAGE_REPOSITORY_NAME}" \
--set deployment.image.digest="${IMAGE_DIGEST}" \
--set deployment.ingress.hostName="${IS_HOSTNAME}" \
--set deploymentToml.account.recovery.endpoint.auth.hash="${ACCOUNT_RECOVERY_ENDPOINT_AUTH_HASH}" \
--set deploymentToml.database.identity.url="${DATABASE_IDENTITY_URL}" \
--set deploymentToml.database.identity.driver="com.microsoft.sqlserver.jdbc.SQLServerDriver" \
--set deploymentToml.database.identity.type="mssql" \
--set deploymentToml.database.identity.username="${DATABASE_IDENTITY_ENCRYPTED_USER}" \
--set deploymentToml.database.identity.password="${DATABASE_IDENTITY_ENCRYPTED_PASSWORD}" \
--set deploymentToml.database.shared.url="${DATABASE_SHARED_URL}" \
--set deploymentToml.database.shared.driver="com.microsoft.sqlserver.jdbc.SQLServerDriver" \
--set deploymentToml.database.shared.type="mssql" \
--set deploymentToml.database.shared.username="${DATABASE_SHARED_ENCRYPTED_USER}" \
--set deploymentToml.database.shared.password="${DATABASE_SHARED_ENCRYPTED_PASSWORD}" \
--set deploymentToml.database.user.url="${DATABASE_USER_URL}" \
--set deploymentToml.database.user.driver="com.microsoft.sqlserver.jdbc.SQLServerDriver" \
--set deploymentToml.database.user.type="mssql" \
--set deploymentToml.database.user.username="${DATABASE_USER_ENCRYPTED_USER}" \
--set deploymentToml.database.user.password="${DATABASE_USER_ENCRYPTED_PASSWORD}" \
--set deploymentToml.database.consent.url="${DATABASE_CONSENT_URL}" \
--set deploymentToml.database.consent.driver="com.microsoft.sqlserver.jdbc.SQLServerDriver" \
--set deploymentToml.database.consent.type="msql" \
--set deploymentToml.database.consent.username="${DATABASE_CONSENT_ENCRYPTED_USER}" \
--set deploymentToml.database.consent.password="${DATABASE_CONSENT_ENCRYPTED_PASSWORD}" \
--set deployment.externalJKS.enabled=true \
--set deploymentToml.keystore.internal.fileName="internal.jks" \
--set deploymentToml.keystore.internal.password="${KEYSTORE_INTERNAL_ENCRYPTED_PASSWORD}" \
--set deploymentToml.keystore.internal.keyPassword="${KEYSTORE_INTERNAL_ENCRYPTED_KEY_PASSWORD}" \
--set deploymentToml.keystore.primary.fileName="primary.jks" \
--set deploymentToml.keystore.primary.password="${KEYSTORE_PRIMARY_ENCRYPTED_PASSWORD}" \
--set deploymentToml.keystore.primary.keyPassword="${KEYSTORE_PRIMARY_ENCRYPTED_KEY_PASSWORD}" \
--set deploymentToml.keystore.tls.fileName="tls.jks" \
--set deploymentToml.keystore.tls.password="${KEYSTORE_TLS_ENCRYPTED_PASSWORD}" \
--set deploymentToml.keystore.tls.keyPassword="${KEYSTORE_TLS_ENCRYPTED_KEY_PASSWORD}" \
--set deploymentToml.superAdmin.password="${SUPER_ADMIN_ENCRYPTED_PASSWORD}" \
--set deploymentToml.superAdmin.username="${SUPER_ADMIN_ENCRYPTED_USERNAME}" \
--set deploymentToml.truststore.password="${TRUSTSTORE_ENCRYPTED_PASSWORD}" \
--set deploymentToml.identity.authFramework.endpoint.appPassword="${IDENTITY_AUTH_FRAMEWORK_ENDPOINT_ENCRYPTED_APP_PASSWORD}" \
--set deploymentToml.encryption.key="${SYMMETRIC_ENCRYPTED_KEY}" \
--set deployment.secretStore.enabled=true \
--set deployment.secretStore.azure.keyVault.name="${AZURE_KEY_VAULT_NAME}" \
--set deployment.secretStore.azure.keyVault.resourceGroup="${AZURE_KEY_VAULT_RG}" \
--set deployment.secretStore.azure.keyVault.resourceGroup="${AZURE_KEY_VAULT_RG}" \
--set deployment.secretStore.azure.keyVault.servicePrincipalAppID="${AZURE_KEY_VAULT_SP_APP_ID}" \
--set deployment.secretStore.azure.keyVault.subscriptionId="${AZURE_SUBSCRIPTION_ID}" \
--set deployment.secretStore.azure.keyVault.tenantId="${AZURE_TENANT_ID}" \
--set deployment.persistence.enabled=true

If it is required to add additional configuration other than what are parameterised in deployment.toml file, you can override the Helm value deploymentToml.extraConfigs

Compatibility

Values