Follow this guide to set up a Joyous Azure Active Directory Integration
About this integration
The Joyous integration to Azure AD can be used for one or both of the following purposes:
- People Data: Import the people you want to participate in Joyous conversations.
- Single Sign-On (SSO): Enable leaders to sign in to Joyous with Microsoft credentials.
People data
Joyous imports people from an AD group. This group should be created with dynamic rules to control who is and isn't imported into Joyous based on your requirements. (e.g. Active Users only, Exclude contractors).
After setup the synchronization will run daily, the specific time of day can be configured if required.
When synchronizing employees we use a feature of the Microsoft Graph API to select their manager Id and build relationships within Joyous based on that.
The required attributes are:
- id (objectId)
- userPrincipalName | mail (email)
- givenName
- surname
Additional attributes can be imported into Joyous and used as data filters, including extension (custom) attributes. We recommend at least the following:
- jobTitle
- department
- city
If you have a custom employee id in addition to the Active Directory id, we recommend importing this as well.
Single Sign-On
In line with industry best practices and Microsoft’s recommendation for SSO we support using OpenID Connect with Azure Active Directory (AAD) or Office 365 (O365).
If the email address entered on our sign-in screen corresponds to an organisation using Microsoft SSO the user is offered a Sign In With Microsoft button which redirects to Microsoft so that the Joyous application can obtain an access token.
The access token is then used to request a user identifier via the Microsoft Graph API which can be associated with a user in the Joyous application.
The initial setup for SSO needs to be carried out with an account that has the AD Global Admin role. Using this account ensures Leaders are not presented with a permissions popup every time they sign in through Single Sign-On.
Setup Process
Step 1 - Customer:
- Decide which attributes to import into Joyous. Details on how to find extension attribute names can be found in Microsoft Azure Active Directory documentation.
- Create a "Joyous" group in AD with the required member rules to identify who should receive Joyous conversations (e.g. Active users, exclude Contractors).
Step 2 - Joyous:
- Configure a temporary account with your email address and trigger an email that lets you set a password and sign in.
Step 3 - Customer:
- Sign in to Joyous (go.joyoushq.com) with the temporary account.
- Navigate to the Configure page and click on Sync with Active Directory.
- Authenticate with Microsoft using an account that has the AD Global Admin role.
A service account is the best option for this. The created Microsoft refresh token is tied to the account used in this step. Certain user actions (e.g. resetting password) will revoke all refresh tokens and require re-setup.
- Select the Joyous AD group.
This will trigger the synchronization and set up the reoccurring daily synchronizations.
Step 4 - Joyous:
- Perform data checks.
- Remove temporary account.
Step 5 - Customer (only if using SSO):
- Test leader sign in. If configured with the AD Global Admin role the permissions popup should not appear.
After completing these 5 steps your integration is complete.
Data Security at Joyous
Please download this PDF if you would like to understand more about how we handle data security at Joyous.