Troubleshooting Federated Authentication
Federated Authentication Process Overview¶
Diagrams are provided that describe the steps that occur during authentication and session establishment through a CMSG for Federated User Authentication with or without Single Sign-On configured. The diagrams are numbered, so the flow can be followed by the numbers to determine which components are in use at any given step in the process, and instructions are be provided for how to obtain logs from those components in the event of a failure.
Authentication Process¶
The diagram shows the process of authentication up until just before the start of a PCoIP Session for the case where Federated Authentication is configured, and Single Sign-On is not.
| Step | Visual | Description | Potential Types of Failures | Components Involved |
|---|---|---|---|---|
| 1 |  |
The user opens up the PCoIP Client from their computer. | Client failures, such as crashing. | PCoIP Client |
| 2 |  |
From the list of configured connections, the user selects the CMSG configured for Federated User Authentication. | Networking errors between the client and connector. Connector is misconfigured or failing |
- PCoIP Client - Connection Manager |
| 3, 4 |  |
The CMSG instructions the PCoIP Client to perform Federated User Authentication and the user's web browser is opened to the organization's Identity Provider. | Connector provides an incorrect client ID.  Networking errors between the user's computer and the Identity Provider. |
- PCoIP Client Connection Manager, Federated Authentication Service - Identity Provider. |
| 5, 6 |   |
The user provides their credentials or any other authentication means to the Identity Provider. | Incorrect credentials.  |
Identity Provider. |
| 7 | NA | The user returns to their PCoIP Client and the client provides the user's proof of authentication to the CMSG. The CMSG validates that authentication against the Identity Provider. | Incorrectly configured return URL in the Identity Provider. Untrusted certificate between the CMSG and Identity Provider. |
- PCoIP Client - Connection Manager - Federated Authentication Service - Third-Party Broker - Identity Provider |
| 8, 9 |  |
CMSG obtains the user's list of desktops (or pools) and returns them to the client to be displayed to the user. | - Network failures between the CMSG and Broker. - User is not configured in the Broker or has no desktops or pools entitled to them.  |
- PCoIP Client - Connection Manager - Third-Party Broker |
| 10 | |
The user selects a desktop (or pool). | Desktop fails to start  |
- PCoIP Client - Connection Manager - Broker |
| 11 |  |
The user is prompted at the PCoIP Client to enter their username and password. Note This step only occurs if SSO is NOT configured. |
- User provides incorrect credentials. - PCoIP Agent is unable to authenticate the user using the credentials. |
- PCoIP Client - Connection Manager - Broker - PCoIP Agent |
| - | The PCoIP session is established and the client is connected to the remote desktop. | - PCoIP Agent is unable to obtain authentication for the user. - Authentication of the user fails. |
- PCoIP Agent - Federated Authentication Service |
Single Sign-On
The diagram describes the steps to authenticate to a CMSG and select a desired remote workstation desktop using Federated User Authentication with Single Sign-On.
The table continues from the table above for Federated Authentication and adds the steps for where Single Sign-On is configured and attempted.
| Step | Visual | Description | Potential Types of Failures | Components Involved |
|---|---|---|---|---|
| 11 |  |
The user is prompted to enter their username and password. | - SSO is not supported by the Agent. - SSO is disabled (see --enable--sso flag, check current configuration) |
- Connector (Connection Manager, Broker) - PCoIP Agent |
| 12 |  |
The user connects to a session and is presented with the login screen. | - Certificate issue. Connector may have been configured with incorrect certificate files. Agent was not able to login with the certificate (Check --sso-signing-* or --sso-enrollment-* installation flags, check current configuration). |
- PCoIP Agent - Connector (Connection Manager, Broker) |
| 13 | The PCoIP session is established and the client is connected to the remote desktop. | - PCoIP Agent is unable to obtain authentication for the user. - Authentication of the user fails. |
- PCoIP Agent - Federated Authentication Service |
Obtaining Logs¶
The table above describes the components that may contain logs to describe errors if a failure occurs. This section provides information or references to how to obtain logs for each HP provided component:
-
PCoIP Client
-
Connector
-
Connection Manager:
sudo docker service logs pcoipcm_cm - Federated Auth service:
sudo docker service logs pcoipcm_fa
Agent logs are only necessary in troubleshooting if using SSO
- PCoIP Agent