Versions Compared

Version Old Version 3 New Version 4
Changes made by

Denise McGettigan

Denise McGettigan

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

This page outlines how to configure Phocas with Microsoft Entra ID (previously called Azure AD) to enable single sign-on (SSO), a process typically carried out by the IT person in your organization with access to Entra ID.

The process involves moving between the two applications . The following in five key steps are , as outlined in detail below:Enable SSO in Entra ID > Enter the Phocas SSO details into Entra ID > Enter the Entra ID SSO details into the Phocas and complete the SSO setup > Add the Phocas users and groups into Entra ID > Edit the user accounts in Phcoas to use the Entra ID usernames. At the bottom of the page, you'll find some troubleshooting tips.

Step 1: Enable SSO in Entra ID

:

  1. Click + New > Enterprise Application.

  2. Click + Create your own application.

  3. Enter an application name in the text box.

  4. Select this option: Integrate any other application you don’t find in the gallery (Non-gallery).

    Image Modified

  5. Click Create.

  6. In the 2. Set up single sign on panel, click Get started.

    Image Modified

  7. Click SAML.

    Image Modified

  8. In the Basic SAML Configuration panel,click the Edit button. Keep this screen open.

Step 2: Enter the Phocas SSO details into Entra ID

:

  1. In Phocas, click Administration > Configuration, then scroll down to the Single sign-on (SSO) > Service Provider section.

  2. Copy the Entity ID from Phocas, then in the Entra ID Identifier (Entity ID) section, click Add identifier and paste the ID into the box.

  3. Copy the ACS URLfrom Phocas, then in the Entra ID Reply URL (Assertion Consumer Service URL) section, click Add reply URL, and paste the URL into the box.

    image-20240326-030107.pngImage Modified

  4. Click Save.

Step 3: Enter the Entra ID SSO details into

the Phocas:

Phocas and complete the SSO setup

  1. Enter the Entra ID SAML certificate:

    1. On the Entra ID Single Sign On page, scroll down to the 3 SAML Certificatessection and download the Certificate (Base64) file.

    2. Open the downloaded certificate file in Notepad and copy the contents.

    3. On the Phocas Configuration page, paste the copied certificate contents into the X509 Certificatebox.

  2. Copy the Login URLfrom Entra and paste it into the Single Sign On Service URLbox in the Indentity Provider (IP) section of the Phocas Configuration page.

  3. Copy the Entra Identifierfrom Entra and paste it into the Entity IDbox in the Indentity Provider (IP) section of the Phocas Configuration page.

    Image Modified

  4. Complete the SSO setup on the Phocas Configuration page, then click Save. In Entra ID, add

Step 4: Add the Phocas users and groups

:

into Entra ID

  1. Click Users and groups in the left-hand menu.

  2. Click + Add user/group.

  3. Click None selected.

  4. Locate and select the user(s) or group(s) you want to have access to Phocas, then click Select at the bottom.

  5. Click Assign.

Step 5: Update the user accounts in Phocas to use the Entra ID usernames

In Phocas, update the user accounts (or create new user accounts) to use the Entra ID usernames. For example, use the email address or User Principal Name (UPN).

  • The usernames depend on the source attribute sent from Entra ID. This can be found in the Single sign-on > Attributes & Claims section.

    Image Modified

  • Here’s an example of updated usernames in Phocas:

    image-20240319-024807.pngImage Modified

Troubleshooting

If the user signs in to Phocas using SSO and returns to the sign-in page, the issue is most likely a user authentication issue. The username in Entra must match the username in Phocas; just a matching email address will not work.

If you have permission to view your Phocas logs, you can check whether the username is correct in Phocas.

Go to Logs > Security and see what the Login failed via ‘SAML' entry shows for the user and what the error message is. Here is an example of such a log:

Code Block
Login failed via 'SAML' for user 'john@example.com' with ID '' 
from IP address 'xx.xx.xx.xx' with User Agent 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) 
AppleWebKit/537.36 (KHTML, like Gecko) Chrome/117.0.0.0 Safari/537.36 Edg/117.0.2045.31' 
due to reason 'InvalidUser'

If the SSO is not working and the Logs > Security displays the following message, the configuration in Phocas is likely wrong. Repeat the steps above to set up the configuration again.

Code Block
Login information is incorrect. SAML configuration may be incorrect.

If you continue to have issues after setup, please contact our Support team.

Key steps in the process:

Table of Contents
minLevel1
maxLevel2
outlinefalse
styledisc
typelist
printabletrue