Deploy Genesys Authentication

From Genesys Documentation
Revision as of 13:00, May 19, 2026 by WikiSysop (talk | contribs)
Jump to: navigation, search
This topic is part of the manual Genesys Authentication Private Edition Guide for version Current of Genesys Authentication.

Learn how to deploy Genesys Authentication into a private edition environment.

Assumptions

  • The instructions on this page assume you are deploying the service in a service-specific namespace, named in accordance with the requirements on Creating namespaces. If you are using a single namespace for all private edition services, replace the namespace element in the commands on this page with the name of your single namespace or project.
  • Similarly, the configuration and environment setup instructions assume you need to create namespace-specific (in other words, service-specific) secrets. If you are using a single namespace for all private edition services, you might not need to create separate secrets for each service, depending on your credentials management requirements. However, if you do create service-specific secrets in a single namespace, be sure to avoid naming conflicts.
Important
Make sure to review Before you begin for the full list of prerequisites required to deploy Genesys Authentication.

Prepare your environment

To prepare your environment for the deployment, complete the steps in this section for Google Kubernetes Engine (GKE).

GKE

Log in to the GKE cluster from the host where you will run the deployment: 

gcloud container clusters get-credentials <cluster>
Create a new namespace for Genesys Authentication with a JSON file that specifies the namespace metadata. For example, create-gauth-namespace.json: 
{
  "apiVersion": "v1",
  "kind": "Namespace",
  "metadata": {
    "name": "gauth",
    "labels": {
      "name": "gauth"
    }
  }
}
Execute the following command to create the namespace:
kubectl apply -f create-gauth-namespace.json
Confirm the namespace was created:
kubectl describe namespace gauth

AKS

Log in to the AKS cluster from the host where you will run the deployment: 

az aks get-credentials --resource-group <resource-group> --name <cluster-name> --admin
Create a new namespace for Genesys Authentication with a JSON file that specifies the namespace metadata. For example, create-gauth-namespace.json: 
{
  "apiVersion": "v1",
  "kind": "Namespace",
  "metadata": {
    "name": "gauth",
    "labels": {
      "name": "gauth"
    }
  }
}
Execute the following command to create the namespace:
kubectl apply -f create-gauth-namespace.json
Confirm the namespace was created:
kubectl describe namespace gauth

Deploy

To deploy Genesys Authentication, you'll need the Helm package and your overrides file. Copy values.yaml and the Helm package (gauth-<version>.tgz) to the installation location.

For debugging purposes, use the following command to render templates without installing so you can check that resources are created properly: 

helm template --debug /gauth-<version>.tgz -f values.yaml

The result shows Kubernetes descriptors. The values you see are generated from Helm templates, and based on settings from values.yaml. Ensure that no errors are displayed; you will later apply this configuration to your Kubernetes cluster.

Now you're ready to deploy Genesys Authentication: 

helm install gauth ./gauth-<version>.tgz -f values.yaml -n gauth

Configure external access

Follow the instructions for either GKE or AKS to make the Genesys Authentication services accessible from outside the cluster.


Provision ingresses for GKE or AKS

After deploying, make Genesys Authentication services accessible from outside the GKE or AKS cluster using the NGINX Ingress Controller.

Create a YAML file called gauth-ingress.yaml with the content below. Note: Replace gws.<domain> and gauth.<domain> with your GWS and Genesys Authentication domains, such as gws.test.dev.
apiVersion: extensions/v1beta1
kind: Ingress
metadata:
  name: gauth-gws-ingress
  namespace: gauth
  annotations:
    # add an annotation indicating the issuer to use.
    cert-manager.io/cluster-issuer: "selfsigned-cluster-issuer"
    # Custom annotations for NGINX Ingress Controller
    kubernetes.io/ingress.class: "nginx"
    nginx.ingress.kubernetes.io/ssl-redirect: "false"
    nginx.ingress.kubernetes.io/use-regex: "true"
spec:
  rules:
  - host: gws.<domain> - e.g. gws.test.dev
    http:
      paths:
        - path: /ui/auth/.*
          backend:
            serviceName:  gauth-auth-ui
            servicePort: 80
        - path: /auth/.*
          backend:
            serviceName:  gauth-auth
            servicePort: 80
        - path: /environment/.*
          backend:
            serviceName:  gauth-environment
            servicePort: 80
  tls:
  - hosts:
    - gws.<domain> - e.g. gws.test.dev
    secretName: gauth-gws-ingress-cert
---
apiVersion: extensions/v1beta1
kind: Ingress
metadata:
  name: gauth-gauth-ingress
  namespace: gauth
  annotations:
    # add an annotation indicating the issuer to use.
    cert-manager.io/cluster-issuer: "selfsigned-cluster-issuer"
    # Custom annotations for NGINX Ingress Controller
    kubernetes.io/ingress.class: "nginx"
    nginx.ingress.kubernetes.io/ssl-redirect: "false"
    nginx.ingress.kubernetes.io/use-regex: "true"
spec:
  rules:
  - host: gauth.<domain> - e.g. gauth.test.dev
    http:
      paths:
        - path: /ui/auth/.*
          backend:
            serviceName:  gauth-auth-ui
            servicePort: 80
        - path: /auth/.*
          backend:
            serviceName:  gauth-auth
            servicePort: 80
 
        - path: /environment/.*
          backend:
            serviceName:  gauth-environment
            servicePort: 80
  tls:
  - hosts:
    - gauth.<domain> - e.g. gauth.test.dev
    secretName: gauth-gauth-ingress-cert
Create ingresses with the following command:
kubectl apply -f gauth-ingress.yaml -n gws

Validate the deployment

Check the installed Helm release: 

helm list

The results should show the Genesys Authentication deployment details. For example: 

NAME    NAMESPACE       REVISION        UPDATED                                 STATUS          CHART           APP VERSION
gauth   gauth           1               2021-05-20 11:56:32.5531685 +0530 +0530 deployed        gauth-0.1.77    0.1

Check the gauth namespace status: 

helm status gauth

The result should show the namespace details with a status of deployed: 

NAME: gauth
LAST DEPLOYED: Thu May 20 11:56:32 2021
NAMESPACE: gauth
STATUS: deployed
REVISION: 1
TEST SUITE: None

Check the Genesys Authentication Kubernetes objects created by Helm: 

kubectl get all -n gauth

The result should show all the created pods, service ConfigMaps, and so on.

Finally, verify that you can now access Genesys Authentication at the following URL: https://<hostname>/ui/auth/sign-in.html

Genesys Service Authentication Cut Over Guide

How Cutover Works

The new auth service (gauth-service-authentication) uses the same Postgres database and Redis cluster as the old auth service (gauth-auth), but with different table formats and token storage formats.

Database (Postgres)

data Old Auth table name New Auth Table name
Clients oauth_client_details oauth2_client_details
Contact Centers client_contact_centers client_contact_centers2


Automatic migration: When the new auth service starts with DB_INIT_DB=true (default), Flyway runs migration `V1.7.1__CopyOauth2ClientDetailsFromOldTable.sql` which copies all client data from old tables to new tables. This happens once on first startup. Subsequent restarts skip it (already applied).

In our helm charts, its enabled by default

services:
  # Switch between OLD AUTH (false) and NEW AUTH (true)
  # Set to true to use gauth-service-authentication-eks
  # Set to false to use gauth-auth-eks (default)
  useNewAuth: false

  secrets:
    useSecretProviderClass: false
  # Number of pod replicas, recommended to be N+1
  replicas: 3
  location: /
  db:
    init: true # It enables automatic migration
    poolSize: 3

Verification:

1.Check new auth pod logs for:

kubectl logs -n gauth <new-auth-pod> | grep -i "migrat"
i. Expected output (first startup):
Migrating schema "public" to version "1.7.1 - CopyOauth2ClientDetailsFromOldTable"

Successfully applied 1 migration(s) to schema "public"
ii. Or if already migrated (subsequent restarts):
Schema "public" is up to date. No migration necessary.

2. Also you can verify client data via the operations API on the new auth pod:

kubectl port-forward -n gauth <new-auth-pod> 8080:8080
curl -u <admin_username>:<admin_password> http://localhost:8080/auth/v3/ops/clients
If clients are returned, the migration was successful.

Redis (Token Storage)

Old Auth New Auth
Serialization JDK binary Jackson JSON
Key prefix configurable (empty) GWS:Auth:V3:
Token keys plain token values SHA-256 hashed
Data model OAuth2AccessToken + OAuth2Authentication OAuth2Authorization (unified)


Tokens are NOT migrated:

Old tokens stored by old auth cannot be read by new auth due to incompatible serialization formats.

See Step 5 and Step 6 for post-cutover actions required.

Rollback Considerations

If you rollback to old auth ( useNewAuth: false):

  • Tokens created by new auth become invalid (same incompatibility in reverse)
  • Dependent services must be restarted again
  • Users must re-login again

Prerequisites

  • gauth Helm chart version >= 100.0.101+0258 (includes new auth service support)
  • gauth-infra-bg Helm chart version >= 100.0.101+36 (only if you use this chart)

Auth Traffic Routing Tables

i.Customers (using gauth chart only)

Single chart manages both pods and ingress. No dependency on gauth-infra-bg.

services.useNewAuth services.service_auth.externalAuth.enabled /auth/ routes to /auth/v3/oauth/token routes to
false false Old auth Old auth (same pods)
false N/A (services.auth.externalAuth.enabled: true) Old auth Old auth ext (dedicated pods)
true false New auth New auth (same pods)
true true New auth New auth ext (dedicated pods)

ii. Customers (using both gauth + gauth-infra-bg charts)

Both charts create ingresses. Values must be kept in sync to avoid conflicting routing.

services.useNewAuth (gauth) active.useNewAuth (infra-bg) active.externalAuth (infra-bg) /auth/ routes to /auth/v3/oauth/token routes to
false false false Old auth Old auth (same pods)
false false true Old auth Old auth ext (dedicated pods)
true true false New auth New auth (same pods)
true true true New auth New auth ext (dedicated pods)

Important: Always set services.useNewAuth and active.useNewAuth to the same value. Mismatched values will result in two ingresses pointing to different auth services, causing unpredictable routing behavior.

Helm Values Reference:

Parameter Description Valid Values Default
services.useNewAuth Controls which auth service the main chart's ingress routes traffic to. When true, routes /auth/ to new auth (gauth-service-authentication). When false, routes to old auth (gauth-auth). Note: If on-premise customers also use the gauth-infra-bg chart, this value must be set in sync with active.useNewAuth in that chart to avoid conflicting ingress routing true or false false
services.service_auth.externalAuth.enabled Deploys dedicated new auth ext pods (gauth-service-auth-ext) for handling /auth/v3/oauth/token traffic separately. Pods are deployed but only receive traffic when services.useNewAuth: true. Note: For on-premise customers using gauth-infra-bg, also set active.externalAuth: true in that chart. true or false false
services.auth.externalAuth.enabled Deploys dedicated old auth ext pods (gauth-auth-ext) for handling /auth/v3/oauth/token traffic separately. Pods are deployed but only receive traffic when services.useNewAuth: false. Note: For on-premise customers using gauth-infra-bg, also set active.externalAuth: true in that chart. true or false false
active.useNewAuth Controls which auth service the infra-bg chart's ingress routes traffic to. When true, routes /auth/ to new auth (gauth-service-authentication). When false, routes to old auth (gauth-auth). Note: Must be set in sync with services.useNewAuth in the gauth chart to avoid conflicting ingress routing. true or false false
active.externalAuth When true, creates a separate ingress path for /auth/v3/oauth/token routing to the dedicated ext pods. The target (old ext or new ext) is determined by active.useNewAuth. Note: Corresponding ext pods must be deployed via services.service_auth.externalAuth.enabled or services.auth.externalAuth.enabled in the gauth chart. true or false true

Step 1: Deploy gauth chart with both old and new auth services

By default, both old auth and new auth pods are deployed. Traffic routes to old auth initially.

Update your values file:
services:
  useNewAuth: false    # Traffic routed to OLD AUTH
  service_auth:
    externalAuth:
      enabled: true    # Deploy new auth ext pods
    jks:
      enabled: true
      secret:
        create: false
        name: gauth-jks
    env:
      GWS_JAVA_OPTIONS_HEAPSIZE: ""
  auth:
    externalAuth:
      enabled: true    # Keep old auth ext pods running
Note: The externalAuth sections are only needed if you use dedicated external auth pods for the /auth/v3/oauth/token endpoint. If you do not use external auth, omit these sections.


Helm chart default value for new auth service is 100.0.001.0192

Update this to latest new auth service version  100.0.001.0193 in your values.yaml
gauth-service-authentication: 100.0.001.0193


Deploy: 
helm upgrade --install gauth ./gauth-<version>.tgz -f <your-values-file>.yaml -n gauth --wait --timeout 600s
Verify all deployments are running:
kubectl get deployments -n gauth
Expected:
gauth-auth-<release>                    2/2
gauth-service-authentication-<release>  2/2
gauth-environment-<release>             2/2
gauth-auth-ui-<release>                 2/2
Note: If you use external auth, you will also see gauth-auth-ext-<release> and gauth-service-auth-ext-<release> deployments.

Step 2: Verify new auth service health

Check that new auth pods are running and healthy:
kubectl get pods -n gauth -l gauth=service-auth
kubectl exec -n gauth <new-auth-pod> -- curl -s http://localhost:8081/health
Expected: {"status":"UP"} Verify service started successfully in logs:
kubectl logs -n gauth <new-auth-pod> | grep -i "Started"
Expected log message indicating successful startup:
Started AuthorizationServerApplication in X seconds
If health check fails, check logs for errors:
kubectl logs -n gauth <new-auth-pod> --tail=100

Step 3:  Pre-cutover functional test

Before switching traffic, verify new auth functionality by calling the token endpoint directly via port-forward:
kubectl port-forward -n gauth <new-auth-pod> 8080:8080
Then test:
curl -X POST http://localhost:8080/auth/v3/oauth/token \
  -d "grant_type=client_credentials&client_id=<id>&client_secret=<secret>"
Expected: A valid JSON response with access_token, token_type, and expires_in fields. If the response contains an error, check the pod logs for details before proceeding with cutover.

Step 4: Cutover - Switch traffic to new auth

Update gauth chart values:
services:
  useNewAuth: true  # Switch traffic to new auth
Deploy:
helm upgrade --install gauth ./gauth-<version>.tgz -f <your-values-file>.yaml -n gauth --wait --timeout 600s
Verify ingress is updated to point to new auth service:
kubectl get ingress -n gauth -o yaml | grep -A5 "path: /auth/"
Expected output (confirming traffic routes to new auth):
path: /auth/
pathType: ImplementationSpecific
backend:
  service:
    name: gauth-service-authentication-<release>
    port:
      number: 8080
If you still see gauth-auth-<release> as the backend service name, the cutover has not taken effect.

Step 5: Validate cutover

Test token endpoint via the public URL to confirm traffic is flowing through the new auth service:
curl -X POST https://<gauth-host>/auth/v3/oauth/token \
  -d "grant_type=client_credentials&client_id=<id>&client_secret=<secret>"
Expected: A valid JSON response with access_token, token_type, and expires_in fields. If the response contains an error, check new auth service logs:
kubectl logs -n gauth -l gauth=service-auth --tail=100 -f
Note: If you use external auth, also check ext pod logs:
kubectl logs -n gauth -l gauth=service-auth-ext --tail=100 -f

Step 6: Restart Only the Applicable Services

This restart is required because existing cached tokens become invalid after switching to the new authentication service. These services hold old auth tokens that new auth cannot validate.

Example commands to restart service
kubectl rollout restart deployment gws-service-configuration -n gws
kubectl rollout restart deployment gws-app-provisioning -n gws


i. gws-service-configuration

ii. gws-app-provisoning

ii. GIR(Genesys Interaction Recording) - Speechminer Web service

iv. Nexus

v. CIWD

vi. UCSX (only Azure)

vii. UDM (CDDS-X)

Impact on Existing Logins

  • Existing agent/user sessions will not be terminated automatically.
  • However, ongoing or new read/write operations may fail after the cutover because old tokens (stored with JDK binary serialization) cannot be read by the new auth service (which uses Jackson JSON serialization).

Note: Users and agents must log in again to resume normal operations:

Examples:

  • WWE users: log out and log back in
  • Agent Setup users: log out and log back in

Re-login creates new tokens in the new auth's format. After re-login, all operations work normally.

Step 7: Rollback (if needed)

Switch back to old auth:
services:
  useNewAuth: false  # Route traffic back to old auth
helm upgrade --install gauth ./gauth-<version>.tgz -f <your-values-file>.yaml -n gauth --wait --timeout 600s
Traffic instantly routes back to old auth. Old auth pods are already running, no restart needed.

Note: After rollback, tokens created by new auth become invalid. Dependent services must be restarted again (same as Step 5 and Step 6) and Users must re-login again.

Step 8: Cleanup (after successful cutover)

Once new auth is stable, disable old auth external pods:
services:
  useNewAuth: true
  auth:
    externalAuth:
      enabled: false  # Remove old auth ext pods
Note: This step is only applicable if you use external auth.

Redeploy gauth chart to remove old auth ext pods. Old auth pods remain for safety but receive no traffic.

Additional Cutover Steps for Customers Using gauth-infra-bg Chart

Important: If you deploy the gauth-infra-bg chart in addition to the gauth chart, both charts create ingress resources that control traffic routing. The services.useNewAuth value in the gauth chart and the active.useNewAuth value in the gauth-infra-bg chart must always be kept in sync. Mismatched values will result in conflicting ingress rules, causing unpredictable routing behavior.

Step 4 becomes:

1. Update gauth chart values:
services:
  useNewAuth: true
2. Update gauth-infra-bg chart values:
active:
  useNewAuth: true
  externalAuth: true  # Only if you use external auth
3. Deploy both charts:
# Deploy gauth chart
helm upgrade --install gauth ./gauth-<version>.tgz -f <your-values-file>.yaml -n gauth --wait --timeout 600s

# Deploy gauth-infra-bg chart
helm upgrade --install gauth-infra ./gauth-infra-bg-<version>.tgz -f <your-infra-values-file>.yaml -n gauth --wait

Rollback (Step 7) becomes:

1. Set both values back to false:
# gauth chart
services:
  useNewAuth: false

# gauth-infra-bg chart
active:
  useNewAuth: false
2. Deploy both charts again.
# Deploy gauth chart
helm upgrade --install gauth ./gauth-<version>.tgz -f <your-values-file>.yaml -n gauth --wait --timeout 600s

# Deploy gauth-infra-bg chart
helm upgrade --install gauth-infra ./gauth-infra-bg-<version>.tgz -f <your-infra-values-file>.yaml -n gauth --wait

Retrieved from "https://all.docs.genesys.com/AUTH/Current/AuthPEGuide/Deploy (2026-05-22 21:03:13)"
Comments or questions about this documentation? Contact us for support!