OAUTH Single Sign-On for ZIE for Web Client

Overview

ZIE for Web Client v16.0.1 supports Single Sign-On (SSO) using OAuth 2.0 / OpenID Connect (OIDC) to provide seamless and secure authentication for:

• Host systems (3270 / 5250) using Web Express Logon (WEL) with Credential Mapper
• Domain-based model pages (Config Server access) created using the ZIEWEB Deployment Wizard

With this integration, users authenticate once through their enterprise identity provider (for example, Okta). ZIE for Web Client then leverages the authenticated identity to manage access to host sessions and configuration-based applications, eliminating the need for additional credential prompts.

Config Server Login (Domain-Based Model Pages)

ZIE for Web Client also supports OAuth-based Single Sign-On (SSO) for both domain-based model pages and host systems through Web Express Logon (WEL) configurations generated using the ZIE for WebDeployment Wizard.

Behavior

• After OAuth authentication, the username derived from the email ID is used as the Config Server username.
• Session profiles are fetched based on the group level.

User Management

• If the user exists in the Config Server, the assigned session profiles are loaded automatically.
• If the user does not exist, a new user can be created automatically under the configured group, provided this option is enabled by the administrator.
• Administrators can also pre-create users either manually or by using the DirUtil tool provided with ZIEWEB.

When users access the application (http://<address>:<port>/<context-root>/<page-name.html>), they are presented with an SSO login prompt for authentication. After successful authentication, the username derived from the email ID is used as the Config Server username.

Configuration Steps

1. OAuth Configuration (web.properties)

Update the following properties in the ZIE for Webpublish directory:

oidc_domain=https://<oauth-provider-domain>
client_id=<client-id>
redirect_uri=http://<server-host>:<port>/<context-root>/callback
scope=openid profile email

AuthorizationEndpoint=https://idp.example.com/oauth2/v1/authorize

The AuthorizationEndpoint property specifies the OAuth 2.0 authorization endpoint of the identity provider. This endpoint is used to initiate the OAuth authorization flow by redirecting the user to the identity provider for authentication and consent.

claim_id=preferred_username

The claim_id property specifies the OAuth/OpenID Connect claim that uniquely identifies the authenticated user. When configured in web.properties, the ZIE for Web Client uses this claim to extract the user identity from the OAuth token during authentication.

Ensure all values match the OAuth provider configuration.

2. Client Secret Configuration (web.xml)

Add the OAuth client secret to web.xml:

<context-param>
  <param-name>client_secret</param-name>
  <param-value>[YOUR_CLIENT_SECRET]</param-value>
</context-param>

Replace [YOUR_CLIENT_SECRET] with the actual secret provided by your OAuth provider.

3. Redirect URI Registration

The redirect_uri specified in both web.properties and your OAuth provider must match exactly. The value should use the following format:

Format:

http://<server-host>:<port>/<context-root>/callback

Example:

http://myserver.company.com:9080/zieweb/callback

Host System Login using OAuth 2.0 and Credential Mapper

ZIE for Web Client now supports Single Sign-On (SSO) via OAuth 2.0 for both domain-based model pages and host systems through Web Express Logon (WEL).

This section describes the process of logging into 3270/5250 host systems using Credential Mapper.

Architecture Summary

1. User authenticates with an OAuth 2.0 provider.
2. ZIE for Webreceives and validates the ID Token.
3. User identity information is stored in the HTTP session.
4. The same authenticated identity is reused for:
   • Automatic host logon via WEL Credential Mapper
   • Config Server user identification and session profile loading

Authentication Flow

1. Application Access

The user accesses the ZIE for Webapplication using a URL such as:

http://<server>:<port>/<context-root>/<page>

If OAuth SSO is enabled, ZIE for Web Client redirects the user to the configured OAuth provider for authentication.

2. OAuth Authentication

• The user logs in using enterprise credentials at the OAuth provider.
• On successful authentication, the provider redirects the user back to ZIE for Web Client using the configured redirect URl. (e.g., http://localhost:9080/zieweb/callback).
• The redirect contains an authorization code.

3. Token Exchange and Session Creation

• ZIE for Web Client exchanges the authorization code for an ID Token (JWT).
• The ID Token is validated and stored in the HTTP session.
• The token contains identity attributes such as email, username, and network ID.

4. Token Handling

• ZIE for Web Client extracts the ID Token and stores it in the HTTP session as id_token.
• The ID Token contains user identity attributes like email, name, etc.

5. Credential Mapping 

• When telnet connection is started an SSO auto-start macro is triggered,.
• Macro fetches host system credentials from WEL custom plugin.

We need to configure the credential mapper ZIE for Web server port and user id in ssoplugin.java.

WEL Custom Plugin:

Network Plugin:

During the initial SSO authentication, the Network ID is derived from the id_token provided either in the request parameters or in the headers.

Credential mMapper Plugin: 

In this plugin, the Network ID is mapped to the corresponding host system credentials using configured sources such as a database, RACF, zMFA service, or other credential repositories.

WEL Custom Plugin Deployment (Host Login Only)

• Deploy custom Network and Credential Mapper plugin JARs using the ZIE for Web Client Admin Console.
• Map the plugins under WEL settings.

Host System Login (3270 / 5250) using Credential Mapper

When a host session is started, ZIE for Web Client uses Web Express Logon to automatically authenticate the user to the host system.

Host Login Flow

1. A telnet session is initiated.
2. An SSO auto-start macro is triggered.
3. The macro invokes a WEL custom plugin.
4. The plugin extracts the Network ID from the OAuth ID Token.
5. The Credential Mapper resolves host credentials for the user.
6. The resolved credentials are used to log in to the host system automatically.

Conclusion

OAuth 2.0 integration in ZIE for Web Client delivers a modern, secure, and unified authentication framework. By combining OAuth-based Single Sign-On with Web Express Logon and Credential Mapper, organizations can enable seamless access to both host systems and configuration-based applications while preserving robust security and centralized identity management.