zMFA Authentication Using OpenID Connect (3270)

This feature adds modern Multi-Factor Authentication (MFA) support to Personal Communications 3270 sessions. It replaces the traditional static mainframe password with a temporary Credential (CTC) generated by Z Multi-Factor Authentication (zMFA).

When OpenID Connect (OIDC) is enabled for a 3270 session, Personal Communications opens the system browser and prompts the user to authenticate with the organization's identity provider, such as Keycloak, Okta, or another OIDC-compliant provider. After successful authentication, Personal Communications sends the authenticated identity to zMFA and receives a new CTC. Personal Communications then uses the resolved z/OS user ID and CTC in the host logon macro instead of requiring the user to enter a user ID and password manually.

If OIDC authentication cannot be completed, Personal Communications falls back to the standard 3270 login process. The OIDC failure does not prevent the user from connecting to the session using the normal login method.

Prerequisites

Before enabling OIDC authentication for a 3270 session, ensure that the [OIDC] section in the PCSWIN.INI file is configured. For example: 

[OIDC] 
Domain=https://<idp-host>:<port>/<idp-path> 
ClientId=<client-id> 
RedirectUri=http://localhost:<port>/callback 
ExpectedIssuer=https://<idp-host>:<port>/<idp-path> 
ZmfaServiceUrl=https://<zmfa-host>:<port>/jwt2ctc 
ClaimId=<claim-name>
  • Domain: Specifies the identity provider's base or issuer URL. This parameter is required. The exact path depends on the identity provider. For Keycloak, use the realm URL (…/realms/<realm-name>). For Okta, use the organization's issuer URL (…/oauth2/<auth-server-id>) or the organization domain for the default authorization server. Use the issuer URL provided by your identity provider.
  • ClientId: Specifies the client ID registered with the identity provider. This parameter is required.
  • RedirectUri: Specifies the local callback URI to which the browser returns after authentication. This parameter is required.
  • ExpectedIssuer: Specifies the issuer that Personal Communications expects in the token. This parameter is optional. If it is not specified, Personal Communications uses the issuer returned through OIDC discovery.
  • ZmfaServiceUrl: Specifies the URL of the zMFA jwt2ctc service. This parameter is required unless the URL is configured on the zMFA Authentication tab.
  • ClaimId: Specifies the token claim used to identify the z/OS user ID. This parameter is required only when Use Claim ID is selected.

In addition, ensure that the following prerequisites are met:

  • The zMFA and identity provider server certificates are trusted on the workstation.
  • A valid z/OS user ID is available. The user ID can be specified on the configuration tab, resolved from a token claim, or entered at connection time.
  • The identity provider client and redirect URI are registered and accessible.
  • An OIDC host-logon macro is recorded for the session before OIDC authentication can be used to log on to the host. For more information, see Setting Up the Auto-Logon Macro.

zMFA Authentication Tab

OIDC is configured on the zMFA Authentication tab of the Telnet3270 host definition properties.

  • Tab Components
    • Enable OpenID Connect: Enables or disables OIDC authentication for the session.
    • Enter User ID
      • Uses the z/OS user ID entered in the associated field.
      • The field cannot be left empty. For more information, see Empty static z/OS user ID under Error Messages.

    • Use Claim ID:

      • Retrieves the z/OS user ID from the identity-provider token using the claim name specified by the ClaimId setting in the [OIDC] section of the PCSWIN.INI file. For example, preferred_username.
      • If the claim is missing or cannot be used, Personal Communications cannot resolve the z/OS user ID. For more information, see PCSOIDC003

    • Prompt for User ID: Prompts you to enter the z/OS user ID in a separate dialog each time you connect to the session. For more information, see “ z/OS User ID Dialog.”

    • zMFA Service URL:

      • Specifies the URL of the zMFA service used for the session.
      • The Personal Communications uses the default zMFA Service URL specified in the INI file. A zMFA Service URL must be specified either in this field or in the INI file.

        If this field is left blank, error message will appear. Refer to Empty zMFA Service URL section under Error Messages for more information.

Browser Authentication Timeout

Specifies the number of seconds Personal Communications waits for browser authentication to complete before timing out. The default value is 120 seconds.

  • If authentication does not complete within the specified time, Personal Communications reports PCSOIDC002 and falls back to standard login.
  • While browser authentication is in progress, the Personal Communications session window is inactive, and you cannot interact with the session.
  • If you close the browser without completing authentication, the Personal Communications session window remains inactive until the timeout expires. After the timeout, the window becomes active, and Personal Communications skips OIDC authentication for that connection attempt.

z/OS User ID Dialog

When Prompt for User ID is selected, Personal Communications displays this dialog once at the beginning of each connection, before browser authentication starts.

Enter User ID

Specifies the z/OS user ID for the current connection attempt. The user ID is not saved and is discarded when the session disconnects.

OK Button

Confirms the entered user ID and continues the connection.

If the field is empty or contains only spaces, Personal Communications displays the following message:

z/OS user ID cannot be empty. Please enter the user ID.

Personal Communications then clears the field and returns focus to it so that you can enter a valid user ID.

Cancel Button

Closes the dialog without specifying a z/OS user ID.

  • OIDC authentication does not proceed for the current connection attempt. Personal Communications falls back to standard login, as it does for other OIDC authentication failures.

Setting Up the Auto-Logon Macro

You can record the OIDC auto-logon macro from the existing Record Macro/Script dialog. A new OpenID Connect option is available for recording an OIDC-enabled macro.

OpenID Connect (Record Macro/Script Dialog)

A new OpenID Connect checkbox is available in the zMFA group of the Record Macro/Script dialog. Select this checkbox to identify the macro being recorded as the OIDC host-logon macro.

  • Select the checkbox when recording the OIDC host-logon macro.
  • When selected, Personal Communications sets the recorded macro description to OIDC so that it can identify the macro during host logon.
  • Personal Communications automatically adds ^^ to the beginning of the recorded user ID and stores the password as the $PSS.WD$ placeholder instead of recording the actual password.
  • To create an OIDC host-logon macro, enable OIDC on the zMFA Authentication tab and select the OpenID Connect checkbox before recording the macro.
  • During macro playback, Personal Communications replaces these placeholders with the resolved z/OS user ID and the newly generated CTC. The actual password is never stored or used.

OIDC Logon Flow

When OIDC authentication is enabled, the connection follows this general flow:

  1. Personal Communications opens the browser and prompts you to authenticate with the configured identity provider.
  2. After successful authentication, Personal Communications sends the resolved z/OS user ID and the identity token to zMFA.
  3. zMFA validates the token and returns a new CTC.
  4. Personal Communications uses the resolved z/OS user ID and CTC in the OIDC host-logon macro to complete the host logon.
  5. If any step fails, Personal Communications displays the corresponding error message and falls back to standard login.

Error Messages

Some error messages may be displayed briefly on the Personal Communications status bar in addition to being displayed in a MessageBox.

zMFA (jwt2ctc) Response Codes

The zMFA service returns a return-code (rc) and reason-code (rsn) pair for each jwt2ctc request. Personal Communications maps these response codes to the corresponding PCSOIDC0xx messages described below.

rc rsn Meaning Personal Communications Message
0 N/A Success - CTC returned (none)
8 8 Bad value specified for the JWT PCSOIDC005
44 N/A Authentication was not successful for the token PCSOIDC006
48 (undocumented) Internal service error PCSOIDC008

PCSOIDC001

Error

OIDC configuration is incomplete or invalid. Verify the OIDC configuration.

Explanation: This message indicates that a required setting in the [OIDC] section, such as the client ID, redirect URI, issuer, or endpoint, is missing or incorrect. Personal Communications detects the configuration problem before opening the browser, so authentication is not attempted for the connection.

User Response: Verify the [OIDC] section of the INI file with your Personal Communications administrator. Correct the invalid or missing value and reconnect.

PCSOIDC002

Error

OIDC authentication was not completed. The browser window was closed or the session timed out.

Explanation: This message indicates that authentication did not complete. The browser may have been closed before authentication was completed, or the Browser Authentication Timeout may have expired while Personal Communications was waiting for the identity provider.

User Response: Reconnect and complete authentication within the configured timeout. If the timeout is consistently too short, ask your administrator to increase the Browser Authentication Timeout value on the zMFA Authentication tab.

PCSOIDC003

Error

OIDC could not resolve the z/OS user ID. Verify the z/OS user ID configuration.

Explanation: This message indicates that authentication succeeded, but Personal Communications could not determine the z/OS user ID to send to zMFA. This can occur when Use Claim ID is selected and the configured claim is missing from the identity provider token, contains no value, or contains a value that Personal Communications cannot use.

User Response: Verify that the configured Claim ID matches a claim in the identity provider token. Alternatively, select Enter User ID or Prompt for User ID.

PCSOIDC004

Error

OIDC authentication succeeded, but a CTC could not be retrieved from the zMFA service.

Explanation: This message indicates that authentication completed, but the request to zMFA did not return a usable CTC. The failure is not covered by one of the more specific zMFA response codes.

User Response: Verify that the configured zMFA Service URL is correct and reachable, and then reconnect. If the problem persists, contact your zMFA administrator.

PCSOIDC005

Error

The authentication token was rejected by zMFA. Please try again.

Explanation: This message indicates that zMFA rejected the identity token sent by Personal Communications with rc=8, rsn=8, indicating an invalid JWT value. The token may be malformed, expired, or not accepted by the configured zMFA service.

User Response: Reconnect and authenticate again. If the problem persists, contact your zMFA administrator.

PCSOIDC006

Error

zMFA reported that authentication was not successful. Please try again.

Explanation: This message indicates that sign-in completed but zMFA returned rc=44 (authentication was not successful for the token).

User Response: Contact your zMFA administrator.

PCSOIDC007

Error

OIDC session data could not be accessed after authentication. Reconnect the session and try again.

Explanation: This message indicates an internal Personal Communications state error. The session record could not be located after the CTC retrieval step completed. This error does not indicate a problem with the OIDC or zMFA protocol.

User Response: Reconnect the session and try again. If the problem persists, contact your Personal Communications support team.

PCSOIDC008

Error

zMFA encountered an internal error. Contact your zMFA administrator.

Explanation: This message indicates that zMFA returned rc=48, indicating an internal service error.

User Response: Contact your zMFA administrator. This is a server-side error and is not caused by the Personal Communications OIDC configuration.

Empty zMFA Service URL

zMFA Service URL cannot be empty. Enter the URL.

Empty z/OS User ID

z/OS user ID cannot be empty. Enter the user ID.

Status Bar Messages

The following messages are displayed only on the Personal Communications status bar. They are not displayed in a MessageBox and do not include a PCSOIDC message code.

The Certificate Error and Connection Failed messages are the only OIDC failures that are not displayed in a MessageBox.

  • Authenticating

    Waiting for OIDC authentication...

  • Config Invalid

    The OIDC configuration is incomplete or invalid. Verify the configuration and try again.

  • Opening Browser

    Complete the authentication process in your browser.

  • CTC Acquired

    OIDC authentication completed. CTC acquired successfully.

  • Cache Hit

    Using the cached OIDC token. Browser authentication is not required.

  • User ID Not Resolved

    OIDC authentication succeeded, but the z/OS user ID could not be resolved. Reverting to standard login.

  • zMFA Failed

    OIDC authentication succeeded, but a CTC could not be retrieved from the zMFA service. Reverting to standard login.

  • Auth Failed / Fallback

    Authentication was not completed because the browser window was closed or the session timed out. Reverting to standard login.

  • Session Unavailable

    OIDC authentication is unavailable because the session data could not be accessed. Reverting to standard login.

  • Certificate Error

    OIDC certificate error. The secure connection to the server failed (error code shown). Reverting to standard login.

    Typical cause: An untrusted or expired zMFA server certificate, or a TLS trust problem talking to the zMFA/OIDC server.

  • Connection Failed

    OIDC connection failed. The server could not be reached (error code shown). Reverting to standard login.

    Typical cause: A DNS/network problem, or the zMFA server being down or unreachable.

  • CTC Bad JWT

    zMFA rejected the authentication token (rc and rsn shown). Reverting to standard login.

  • CTC Not Authorized

    zMFA reported that authentication was not successful (rc shown). Reverting to standard login.

  • CTC Service Error

    zMFA reported an internal error (rc shown). Reverting to standard login.

  • OIDC credentials are invalid

    During macro playback, this message is displayed when OIDC authentication succeeds, but Personal Communications cannot resolve the z/OS user ID or retrieve a CTC from the zMFA service.

  • Macro playback failed due to OIDC authentication failure

    This message is displayed when OIDC authentication fails and you attempt to run an OIDC-enabled macro (a macro with the description OIDC).