Versions Compared

Version Old Version 1 New Version 2
Changes made by

Denise McGettigan

Denise McGettigan

Saved on

Key

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

[Re the title, are Azure Ad / Entra the same thing? Or different apps? We switch between both names in steps]

This page outlines how to configure Phocas with Microsoft Azure to enable single sign-on (SSO). The steps involve moving between the two applications.

  1. Enable SSO in Azure:

    1. Click + New Application > + Create your own application.

    2. On the right of your screen, enter an application name in the text box and select this option: Integrate any other application you don’t find in the gallery (Non-gallery) option.

    3. In the application, click 2. Set up single sign on.

    4. Click SAML.

    5. Click the Edit button for Basic SAML Configuration. where?

    6. In the side panel that displays, click Enable SAML and enter a name. Keep this screen open.

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

  3. In Azure, enter the Phocas Service Provider (SP) details:

    1. Copy the Service Provider Entity ID from Phocas and paste it into the Identifier (Entity ID) box in Azure Entra.

    2. Copy the Service Provider ACS URLfrom Phocas and paste it into the Reply URL box in Azure Entra.

      image-20240319-021127.png

  4. Save the application to complete the creation process. how/where?

  5. Open the application in Entra and on the left-hand side, select the section Single Sign On.

  6. Scroll down

until you see Section 3

  1. to section 3 SAML Signing Certificateand download the Certificate (Base64) file.

  2. Open the downloaded certificate file in

notepad

  1. Notepad and copy the contents

into Phocas

  1. .

  2. Back in Phocas, paste the copied certificate contents into the X509 Certificate

fieldNow copy

  1. box.

  2. Enter the Entra details into the Phocas Indentity Provider (IP) section:

    1. Copy the Login URL

field in

    1. from Entra and paste it into the Single Sign On Service URL

field

    1. box in Phocas.

Now copy

    1. Copy the Azure AD Identifier

field in

    1. from Entra and paste it into the Entity ID

field

    1. box in Phocas.

 

  1. Image Modified
15. With that information saved both in Phocas and Microsoft Azure, the users will need to be added to the Phocas Application in Microsoft Azure in

  1. Complete the SSO setup on the Phocas Configuration page, then click Save. [new, need more? add link]

  2. In Azure, add the Phocas users in Users and Groupsin the left-hand menu.

 

16. On the Phocas side, you will need to create/edit the users in Phocas to use the username used to log into Azure e.g. email address or UPN.

Image Removed

 

The username to add for the user account in Phocas is Image Removed

 

Note: If the user logs into

  1. [more how or screenshot? you gave more steps in other steps above]

  2. In Phocas, edit the user accounts (or create new user accounts if required) to use the Azure usernames. For example, use the email address or User Principal Name (UPN) [like one in screenshot below?]. [denise to add link]

    • The usernames are dependent on the source attribute sent from Azure, this can be found in the user attributes & claims section.

    • [correct name? how do i get there?]

      Image Added

    • Example of edited usernames in Phocas:

      image-20240319-024807.pngImage Added

Troubleshooting

If the user signs in to Phocas using SSO and returns back to the Phocas login sign-in page, the issue is most likely a user authentication issue so you will need to check whether . The username in Azure must match the username in Phocas; just a matching email address will not work.

If you have the Logs user permission, you can check whether the username is correct in Phocas.

To check this, go Go to Logs > Security and see what the Login failed via ‘SAML' entry shows for the 'user’ field, user and what the error message is, i.e.. 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'
The user shown here must match a Username in Phocas - just a matching email address will not work.
If the SSO is not working and the Logs > Security shows the line: displays the following message, the configuration in Phocas is likely wrong. The best steps are to get the two URLs and the Certificate again from Entra. [repeat steps above?]
 Code Block
Login information is incorrect. SAML configuration may be incorrect.
Then the configuration in Phocas is likely wrong, and the best steps are to get the 2 URLs and the Certificate again from Entra.
 InfoIf the customer is having issues after setup, the following page can be used for troubleshooting:
Troubleshooting SAML
If you continue to have issues after setup, please contact our Support team. [denise add link]