Set up SSO with Microsoft Entra ID

This page outlines how to set up Phocas and Microsoft Entra ID (Entra), previously called Azure AD, to allow single sign-on (SSO) for your Phocas site.

This is an advanced technical process typically carried out by the IT person in your organization with access to Entra. It involves moving between the two applications in seven key steps, as outlined below. At the bottom of the page, you'll find some troubleshooting tips.

Step 1: Set up SSO in Entra

1. In your Microsoft Entra admin center, click Enterprise applications.

2. Click + New application.

3. Click + Create your own application.

4. Enter a name for the application.

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

   
6. Click Create.

7. In the 2. Set up single sign on tile, click Get started.

   
8. Click SAML.

   
9. In the Basic SAML Configuration panel, click the Edit button. Keep this screen open and proceed to step 2 below.

Step 2: Activate the SSO feature in Phocas

1. In the Phocas menu, click Administration > Configuration.

2. Click the Single sign-on (SSO) tab.

3. Select the Allow SSO via SAML checkbox. The SAML configuration settings display. Keep this screen open and proceed to step 2 below.

Step 3: Enter the Phocas SSO details into Entra

With both the Phocas and Entra screens open side-by-side:

1. In Phocas, in the Service provider (SP) section, copy the Entity ID.

2. In Entra, in the Identifier (Entity ID) section, click Add identifier and paste the ID into the box.

3. In Phocas, copy the ACS URL.

4. In Entra, in the Reply URL (Assertion Consumer Service URL) section, click Add reply URL and paste the URL into the box.

   
5. In Entra, click Save and close the panel. Continue to keep both the Phocas and Entra ID screens open side-by-side.

Step 4: Enter the Entra SSO details into Phocas

With both the Phocas and Entra screens open side-by-side:

1. Obtain the Entra SAML certificate:

   1. In Entra, on the Single Sign On page, scroll down to the 3 SAML Certificates section and download the Certificate (Base64) file.

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

2. In Phocas, in the Identity Provider (IP) section, paste the copied certificate contents into the X509 Certificate box.

3. In Entra, in section 4, copy the Login URL.

4. In Phocas, in the Identity Provider (IP) section, paste the IRL into the Login URL box.

5. In Entra, copy the Microsoft Entra Identifier.

6. In Phocas, in the Identity Provider (IP) section, paste the identifier into the Entity ID box.

   

Step 5: Complete the SSO setup in Phocas

1. In Phocas, in the Identity Provider (IP) section, enter a name for the provider, for example, My Company SSO. This will display as a button on your Phocas Sign in page.

2. Select the required SAML options: Use enhanced SAML security, Update user account with details from IdP on user sign-on, and Automatically create user account if none exists. See the bottom of the Set up single sign-on (SSO) for information about these settings.

3. Click Save.

Step 6: Add the Phocas users and groups into Entra

1. In Entra, 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 7: Update the Phocas accounts with the Entra usernames

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

The usernames depend on the source attribute sent from Entra. 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.

Otherwise, it could be that:

• The Base64 certificate is out of date. When you create the new Microsoft Enterprise app, it takes approximately 5 to 10 minutes for it to be properly provisioned. After it's provisioned, the Base64 certificate changes. If you download and use the certificate before the app is provisioned, the sign-in process won't work. Download the certificate again, open and copy the updated contents, then paste it into into the into the X509 Certificate box in Phocas (see step 4 above).

• Something else in the configuration in Phocas is wrong. Repeat the steps above to set up the configuration again.

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