Create the Azure AS SSO Application

note

The following screenshots and process was correct and valid as of the last update to this documentation (21/11/2024). Microsoft does like to rename and move things around so if something is wrong please let us know via the support options.

Entra application setup

1. Open the Azure portal and sign in as an administrator
2. Search or select Microsoft Entra ID service from the search on left hand menu

3. Navigate to the Enterprise applications section within the Manage menu.

4. Click New application

5. And select Create your own application.

6. Enter the application name. E.g. Aiphoria-Focus-SSO
7. select Integrate any other application you don't find in the gallery (Non-gallery) from the application options
8. Press Create

9. Select Setup single sign-on

10. From the next menu, Select SAML

11. On the next screen you will be asked for two bits of information:
    1. click the 'Edit' button and complete the required fields.
    2. The URLs needed in this section will be provided to you by the Aiphoria support team upon request. Under each section you will need to press the add button to create complete both the Identifier (Entity ID) and Reply URL (Assertion Consumer Service URL) sections.
    3. Press Save at the top of the section

• Identifier: The Identifier or Entity ID represents a globally unique identifier for your Focus service, functioning as the EntityId for SP during authentication requests to the IdP. This identifier is pivotal for the secure exchange of SAML assertions and other authentication-related data between the IdP and Focus.
• Reply URL: The Assertion Consumer Service (ACS) URL is the location where the SAML assertion is sent with a POST request. This URL is used by the IdP to send the SAML assertion to Focus. It acts as a callback URL where Focus expects to receive and consume the SAML response containing the user's identity information.

Perfect, the application is now setup 👍

Data to be provided to Aiphoria

Almost done, but to make the SAML SSO integration work, you will need to provide the IdP metadata back to the Focus support team. The required data is all Within the same Enterprise Application -> Single sign-on settings page.

Focus provides three different ways to configure the IdP metadata. The easiest way is by providing the metadata URL of the Azure AD SSO application.

1. Copy the App Federation Metadata Url from section 3 of your Azure AD SSO application's SAML Certificates section and send to the Focus support team

tip

If you are not able to supply the Metadata URL (preferred method), Focus also supports an upload of the XML file (simply send this to the support team) or adding the data manually, if you need to go down this route, we will require the Sign on URL, Issuer url and the Certificate please contact support if you need more help.

2. You will also need to provide the email domain used for auth e.g. @mycompany.com

Configure user attributes mapping

Focus provides a flexible way to map the user attributes returned from IdP to the user attributes in Focus. Focus will sync the following user attributes from IdP by default:

• id: The unique identifier of the user. Focus will read the nameID claim from the SAML response as the user SSO identity id
• email: The email address of the user. Focus will read the email claim from the SAML response as the user primary email. This is mapped to: emailaddress
• name: The name of the user. This is mapped to: user.displayname

note

If you wish to change or add any mappings please contact support

Assign users to the Azure AD SSO application

Only users assigned to your Azure AD SSO application will be able to authenticate through the Focus Azure AD SSO connector. To assign a user or groups of users to the application follow the steps below:

1. From within the same Enterprise Application -> Single sign-on settings page, select Users and groups
2. Then Add user/group at the top of the page

3. Select the text None Selected and a search menu will open
4. Search for any users or groups you wish to authorize for access to the application
5. Tick the required users or groups
6. The users being added will show on the far right menu

7. Once you are happy with the selected users and groups, press Select at the bottom
8. You will get a confirmation screen with how many users are being added
9. If happy, press Assign

🎉🎉 Congratulations, your authorized users should now be able to login to the Focus portal.🎉🎉

Troubleshooting Common Issues

If you encounter issues during the setup or login process, here are some common problems and their solutions:

• Users cannot log in: Verify that the users are assigned to the Azure AD SSO application. Check the "Users and groups" section to ensure the correct users or groups are added.
• Metadata URL not working: Ensure the Metadata URL is correctly copied and accessible. Test the URL in a browser to confirm it returns the expected XML.
• SAML response errors: Use browser developer tools to inspect the SAML response. Verify that the Identifier and Reply URL match the values provided by Aiphoria.
• Attribute mapping issues: Confirm that the attributes returned by the IdP match the expected mappings (e.g., emailaddress, user.displayname). Contact support if custom mappings are needed.

Security Best Practices

• Always share the Metadata URL or XML file securely. Avoid using insecure channels like unencrypted email.
• Regularly review and update the list of authorized users and groups to ensure only necessary access is granted.

Testing the SSO Setup

Before rolling out the SSO setup to all users, test it with a small group of users to ensure everything works as expected. Use the following steps:

1. Assign a test user to the Azure AD SSO application.
2. Attempt to log in to the Focus portal using the test user's credentials.
3. Verify that the user attributes (e.g., email, name) are correctly synced.

If any issues arise during testing, refer to the troubleshooting section or contact support for assistance.