> ## Documentation Index
> Fetch the complete documentation index at: https://docs.iru.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Advanced Passport Troubleshooting

> Troubleshoot advanced Passport issues in Iru Endpoint. Diagnose token refresh failures, IdP sync problems, keychain errors, and login loop scenarios.

<Callout icon="apple" color="#B84A7A" iconType="regular">This guide applies to Mac computers</Callout>

### Login, Diagnostics, and Network

<CardGroup cols={2}>
  <Card title="Sign in with the full email address" icon="user">
    At the Passport login window, always enter the user's full email address in the username field so the session uses your IdP instead of local authentication. For how the login window and visibility settings interact with Passport, see [Passport Compatibility](/en/endpoint/library/passport/passport-compatibility-with-macos-and-iru-endpoint-features#login-window).
  </Card>

  <Card title="Use Passport Diagnostics" icon="display">
    If a user cannot sign in, open Iru Endpoint Passport Diagnostics with **Command-Shift-K-L** on the Mac. The panel surfaces useful detail, including error messages returned from your IdP.
  </Card>

  <Card title="Confirm network connectivity" icon="wifi">
    Passport must reach your IdP to validate credentials. When you customize the Passport login window, enable the network manager so users can join Wi-Fi if needed. The control respects AirPort security settings in macOS.
  </Card>

  <Card title="Wi-Fi limits and isolation testing" icon="triangle-exclamation">
    Passport shows a Wi-Fi icon at the upper-right of the login window; users can click it to join a password-protected network. Passport does not support captive portals, click-through acceptance pages, or enterprise 802.1X networks that require a separate username and password in that flow. To isolate network issues, try a mobile hotspot or wired Ethernet while testing at the Passport login window.
  </Card>
</CardGroup>

### Ensure Surname (familyName) in Your IdP

Passport requires a **familyName** value in IdP user attributes. Populate **Last name** or the equivalent surname field for every account that signs in with Passport, including service accounts you test with.

### Passport Supported IdPs

The current Iru Endpoint Passport supported IdPs are [Google Workspace](/en/endpoint/library/passport/google-workspace/passport-configuration-with-google-workspace), [Microsoft Entra](/en/endpoint/library/passport/microsoft-entra-id/passport-troubleshooting-with-microsoft-entra-id-formerly-azure-ad), [Okta](/en/endpoint/library/passport/okta/passport-configuration-with-okta), and [OneLogin](/en/endpoint/library/passport/onelogin/passport-configuration-with-onelogin).

### Passport Requirements when using Other IdPs

[Passport configuration](/en/endpoint/library/passport/configure-the-passport-library-item) requires OIDC and ROPG (Resource Owner Password Grant) workflows to function. Check with your IdP to verify that they support these features.

While Iru does offer the option to choose Mac Login or Web Login, set up Passport first using Mac Login, as there can be additional factors when configuring Web Login. You can reference the supported configurations using Google Workspace, Microsoft Entra, Okta, or OneLogin as a resource.

* [Passport Configuration with Google Workspace](/en/endpoint/library/passport/google-workspace/passport-configuration-with-google-workspace)
* [Passport Configuration with Microsoft Entra (formerly Azure AD)](/en/endpoint/library/passport/microsoft-entra-id/configure-passport-with-microsoft-entra-id-mac-login)
* [Passport Configuration with Okta](/en/endpoint/library/passport/okta/passport-configuration-with-okta)
* [Passport Configuration with OneLogin](/en/endpoint/library/passport/onelogin/passport-configuration-with-onelogin)

If you're not using one of the identity providers above, you may still be able to configure Passport using the **Other** option.

### Configure Other IdP

#### Authentication Configuration

* When configuring an IdP other than Google Workspace, Microsoft Entra, Okta, or OneLogin, select the **Other** option from the **Identity provider** drop-down.

#### Authentication Mode

* If you **do not** use multi-factor authentication (MFA), you need to choose Mac Login.

* If you **do** use multi-factor authentication (MFA), you need to choose Web Login.

#### Mac Login

<Steps>
  <Step title="Enter Identity Provider URL">
    Enter the **Identity provider URL**.
  </Step>

  <Step title="Enter Client ID">
    Enter the **Client ID** of the Passport App that you created in your IdP (may also be called App ID)
  </Step>
</Steps>

#### Web Login

<Steps>
  <Step title="Enter Identity Provider URL">
    Enter the **Identity Provider URL**
  </Step>

  <Step title="Enter Client ID">
    Enter the **Client ID** of the Passport App that you created in your IdP (may also be called App ID)
  </Step>

  <Step title="Configure PKCE and Post auth support">
    When using Web Login, your app must support both PKCE (Proof Key for Code Exchange) authentication and POST authentication. Some IdPs may require configuring two different apps.
  </Step>

  <Step title="Set Redirect URI">
    The **Redirect URI** should be your IdP's default Redirect URI in most cases.
  </Step>
</Steps>

### Troubleshooting

There are many factors to consider when troubleshooting Passport issues when selecting the **Other** option for the Passport IdP. This section helps you capture errors, understand them, and adjust configuration.

<AccordionGroup>
  <Accordion title="POST token 401: Invalid user credentials">
    **What you see:**

    `"error":"Unauthorized","error_description":"Authentication Failed: Invalid user credentials"`

    **What to do:**

    * Confirm the username and password with your IdP.
    * If the GET request to your OIDC well-known `openid-configuration` URL returns **200**, the **Identity provider URL** and **Client ID** in the Passport Library Item are typically reaching the IdP correctly. Your IdP may label the client identifier **Application ID**.
  </Accordion>

  <Accordion title="POST token 403: User cannot access the Passport app">
    **What you see:**

    `"error":"access_denied","error_description":"End-user does not have access to this application"`

    **What to do:**

    * In your IdP, confirm the user or group can access the Passport OIDC application and that sign-on or access rules allow it.
    * If the GET request to your OIDC well-known `openid-configuration` URL returns **200**, the **Identity provider URL** and **Client ID** in the Passport Library Item are typically reaching the IdP correctly. Your IdP may label the client identifier **Application ID**.
  </Accordion>

  <Accordion title="Ticket Decode failed">
    **What you see:**

    Ticket decode failed. Failed to login with possible error: Unknown

    **What to do:**

    * Remove the optional **Client secret** from the Passport Library Item, let the device check in, sign out of the local user, and sign in again with Passport.
    * If the error persists, rule out network issues with a mobile hotspot at the Passport login window.
  </Accordion>

  <Accordion title="No key was found matching familyName">
    **What you see:**

    An error occurred fetching user info: No key was found matching "familyName"

    **What to do:**

    * Populate **Last name** or the equivalent surname field for the user in your IdP. Passport requires that attribute.
  </Accordion>
</AccordionGroup>

If you continue to experience issues with Passport, [reach out to Support](/en/iru/iru-support/support-customer-portal).

#### Error Code Lookup

Many IdPs will generate their own specific error codes. Check with your IdP to see if they have a lookup page for reading more about the specific error you are receiving from them. An example of this is the [error code form](https://login.microsoftonline.com/error) from Microsoft for looking up Entra errors.

### Related Articles

<CardGroup cols={2}>
  <Card title="Passport Compatibility with macOS & Iru Endpoint Features" icon="apple" href="/en/endpoint/library/passport/passport-compatibility-with-macos-and-iru-endpoint-features">
    Passport compatibility with macOS and Iru features
  </Card>

  <Card title="Managing Passwords with Passport" icon="key" href="/en/endpoint/library/passport/managing-passwords-with-passport">
    How to manage passwords with Passport.
  </Card>
</CardGroup>