Set up SSO for Phocas in Microsoft Entra ID

User permission: Administration > Configuration

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

The process involves moving between the two applications in five key steps, as outlined below. 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).

   
5. Click Create.

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

   
7. Click SAML.

   
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 URL from Phocas, then in the Entra ID Reply URL (Assertion Consumer Service URL) section, click Add reply URL, and paste the URL into the box.

   
4. Click Save.

Step 3: Enter the Entra ID SSO details into Phocas and complete the SSO setup

1. Obtain the Entra ID SAML certificate. On the Entra ID Single Sign On page, scroll down to the 3 SAML Certificates section and download the Certificate (Base64) file. Open the downloaded certificate file in Notepad and copy the contents.

2. On the Phocas Configuration page, in the Identity Provider (IP) section, paste the copied certificate contents into the X509 Certificate box. Then, copy the Login URL from Entra and paste it into the Single Sign On Service URL box, and copy the Microsoft Entra Identifier from Entra and paste it into the Entity ID box.

   
3. Complete the SSO setup on the Phocas Configuration page, then click Save.

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.

Here’s an example of updated usernames in Phocas:

---

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:

Login failed via 'SAML' for user '[e-mail]' 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.

Login information is incorrect. SAML configuration may be incorrect.

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