Skip to main content

Setting Up Arist for Microsoft Teams

Learn how to install, authorize, and roll out the Arist apps in Microsoft Teams so learners receive courses in the tool they already use, with no separate login.

Platform access level: Org Admins


Setting Arist up in Microsoft Teams delivers courses inside the tool your learners already use, with no separate login and no new system to learn. Because delivery is push-based, your IT team installs and configures the apps ahead of time so they are waiting when a learner's first course arrives. This guide is written for the Microsoft 365 Global Administrator who completes the setup, and it runs in order because each step depends on the one before it.


1. Understand the three Arist apps

Arist registers three apps in your Microsoft 365 tenant, and all three need their permissions approved. Two are installed in Teams, and the third runs in the background without appearing in Teams at all.

  • Arist: The main learning app, shown in the Teams sidebar, where learners open and complete courses. This app is user-facing.

  • Arist Comms: A background notification app that delivers course reminders and alerts through Teams Chat. It runs silently, learners do not interact with it directly, and it should not be pinned.

  • Arist User Sync: A background service that reads your directory to build the learner list. It is not installed in Teams and is never visible to learners, and its permissions are granted when you enable the user sync in Arist.

Chat is used instead of the Activity Feed because learners check it far more often. Learners sign in with their existing Teams identity, so there is no separate password, and authentication is handled through Microsoft Entra.

Note: Because delivery is push-based, learners never go looking for Arist. The app has to be installed for them ahead of time, which is what this guide sets up.


2. Confirm what you need before you begin

Confirm the seven items below in the weeks before your setup session, not on the day itself. Each is a decision, an access grant, or an asset that can take time to track down, and having all seven ready is the difference between a 30-minute setup and a stalled one.

Item

What to confirm

Global Administrator

A Microsoft 365 Global Administrator who can install apps and grant admin consent. A standard IT admin cannot grant admin consent.

Tenant ID

Your Microsoft 365 Tenant ID, found at entra.microsoft.com under Overview.

Global Administrator’s Arist account

The Microsoft Entra Global Administrator also needs an Arist account with Org Admin access to your organization. If they use a dedicated Global Administrator address, create their Arist account using that address. Confirm they can sign in before setup and coordinate access with your Arist contact.

User population

Whether you will sync your entire population or one or more specific Microsoft Entra security groups. This drives how you install and sync.

Branding assets

If white-labeling, the color icon, outline icon, app name, short description, and accent color, ready before install.

Install approach

Whether your tenant uses App Setup Policy or App Centric Management. The install steps in this guide explain how to check.

UPN vs email

Whether your learners' Microsoft login usernames (UPNs) match their email addresses. If they differ, tell your Arist contact before syncing.

Scope your rollout to a Microsoft Entra security group rather than your whole tenant. Security groups do not notify members when they are added, and editing the group is then the only thing you need to do to widen or narrow access later. Set the group up this way:

  • Cloud-native group: Create it in Entra rather than syncing it from on-premises Active Directory, so you can correct membership in the portal immediately.

  • Same group for both: Point the user sync and the Teams app assignment at one group, so the two populations can be reconciled.

  • Membership type: Use assigned membership for your pilot so early access stays scoped, and dynamic membership for production.

Important: Keep the group flat. The Arist user sync does not support nested groups, and Arist cannot guarantee the experience with other group types.


3. Link your Tenant ID in Arist

Linking your Tenant ID is the foundation of the whole integration, because Arist uses it to identify which Microsoft 365 environment to connect to. You do this in the Arist web app with an Org Admin account.

  1. Sign in to the Arist web app with the Global Administrator’s Arist account described in section 2. Confirm that the correct address is shown at the bottom left.

  2. Select your organization’s logo at the top left, choose Organization settings, then Delivery methods, and expand Microsoft Teams.

  3. Confirm that Microsoft Teams tenant ID is populated. If it is not, enter your tenant ID and select Save.

  4. If you do not have Org Admin access, share your Tenant ID with your Arist contact and they will add it for you.

Important: Do not start the next steps until the Tenant ID is linked. Nothing else in this guide works until this step is complete.


4. Make the apps available in Teams

Making apps available is done in the Teams Admin Center. This step marks the two Teams apps as eligible to install across your tenant.

  1. Go to Teams apps, then Manage apps.

  2. Search for Arist, open the app, and set availability to Everyone. If your tenant is on a legacy configuration, use a Permission Policy instead.

  3. Repeat for Arist Comms.

  4. Confirm both apps show as available to everyone before you continue.

Enable both apps at this stage. Skipping Arist Comms breaks the Chat notifications learners rely on for reminders.

Note: Making an app available only makes it eligible for installation. It does not push the app to anyone, and learners will not see Arist in their sidebar until you install it.


5. Grant admin consent

Admin consent authorizes Arist to call specific Microsoft Graph APIs on behalf of your organization. Without it, the apps cannot authenticate learners or send notifications. Your Global Administrator grants consent for each app separately.

  1. In Manage apps, open the Arist app, go to the Permissions tab, and select Grant admin consent.

  2. Sign in with Global Administrator credentials and confirm.

  3. Repeat for Arist Comms.

  4. Confirm both apps show consent as granted before moving on.

Arist uses three app registrations, each scoped to the least access it needs. You grant consent for Arist and Arist Comms here, in the Teams Admin Center. The User Sync registration's permissions are granted separately when you enable user sync in Arist. The table below is the full list for your security team.

App

Permission

What it does

Arist

User.Read

Authenticates the signed-in learner through their Teams email. Scoped to the individual user.

Arist

TeamsActivity.Send.User

Sends an activity notification when a learner has a new course. Write-only and outbound-only.

Arist Comms

User.Read

Authenticates the learner so Chat notifications reach the correct Teams account.

Arist Comms

TeamsAppInstallation.ReadWriteSelfForUser.All

Manages Arist Comms' own install state for automatic updates. Cannot install or modify any other app.

User Sync

User.ReadBasic.All

Reads each learner's name, email address, User Principal Name, contact email, and Microsoft user object ID. Read-only.

User Sync

Group.Read.All

Reads the designated Microsoft 365 or Security Group to identify the target population. Read-only.

User Sync

GroupMember.Read.All

Reads membership of that group to build the learner list. Read-only.

User Sync

User.Read.All (application permission, optional for basic learner sync)

Reads supported Microsoft Entra profile properties, including Extension Attributes 1 to 15, into learner metadata. Required for selected synced user properties. Read-only.

Basic learner sync runs without the additional User.Read.All application permission. Selected metadata properties require that permission, granted to the Arist User Sync app by your Microsoft Entra Global Administrator.

Metadata sync can be enabled for your organization through your Arist Customer Success contact. To add metadata to an existing sync, use Re-consent on the permission banner rather than turning automatic synchronization off and on. For the account, consent, permission-check and field-mapping steps, follow HRIS Integration - Microsoft Teams.

Arist uses that additional metadata in three places.

  • Automations: Content delivery and scheduling can run dynamically based on learner attributes.

  • Reporting: Platform reports can be filtered and broken down by those attributes.

  • Diagnostic: The attributes appear on the participant's profile, so Diagnostic can make recommendations and interpret feedback from an interview.

Important: Arist never reads Teams messages, files, channels, calendars, mailboxes, or SharePoint. Every user sync permission is read-only, and the .All suffix denotes tenant-wide scope, not write access.


6. Apply white-label branding

Applying your own branding is optional. It gives the apps your organization's name, logo, and accent color so Arist appears as a native part of your Teams environment.

Tip: Skip this section entirely if you are keeping the default Arist branding. No assets are needed.

  1. In Manage apps, open the Arist app and click the Customize link at the top of the screen, beneath the App name, to open the Edit customization panel.

  2. Upload your assets and enter your text, using the specifications below.

  3. Save, then repeat for Arist Comms.

  • Color icon: Supply a 192x192 PNG with a transparent background.

  • Outline icon: Supply a 32x32 white outline PNG with a transparent background.

  • App name: Use up to 30 characters.

  • Short description: Use up to 80 characters.

  • Accent color: Provide a hex code.

Important: Make the apps available, apply your branding, and only then install. Microsoft caches an app's icons and name at install time, so installing first means your learners see the default Arist branding until that cache refreshes, which can take several days.


7. Install the apps for your learners

Installing is the step that actually pushes Arist into your learners' Teams sidebars. Because Arist is push-based, pre-installing it ensures the app is already there when a learner's first course arrives. The exact path depends on which install system your tenant uses.

To check which system you have, go to Teams Admin Center, then Manage apps, open Arist, and look at the Users and Groups tab. An Installs section means your tenant uses App Centric Management. If there is no Installs section, use App Setup Policy.


Option A. App Setup Policy (legacy)

  1. Go to Teams apps, then Setup policies.

  2. Edit the Global policy to reach all users, or create a custom policy for a specific group.

  3. Under Installed apps, add both Arist and Arist Comms.

  4. Optionally, add Arist under Pinned apps to pin it to the sidebar.

  5. Save. If you created a custom policy, assign it to the target group through the Group policy assignment tab.


Option B. App-Centric Management (current Microsoft default)

  1. Go to Teams apps, then Manage apps, and select Arist.

  2. Click Edit installs, or go to Users and Groups, then Installs, then Install app.

  3. Select your target users or groups and apply.

  4. Repeat for Arist Comms.

  5. To pin Arist to the sidebar, you still need an App Setup Policy with Arist under Pinned apps. Pinning is not available through App Centric Management alone.

Important: Pin only the main Arist app. Do not pin Arist Comms, because learners receive its reminders in Chat while using the pinned Arist app.

Policy changes and installs can take up to one to two days to propagate, and the first notification can take up to 72 hours after that. This is Microsoft-side behavior, so set expectations with your stakeholders accordingly.


8. Sync your learners

Syncing connects your learners' Teams identities to their Arist accounts so courses reach the right learners. The same Teams admin who granted consent runs this, signed in with Org Admin access. If that Org Admin account was created only for this setup, it can be removed once the sync is running.

Before you sync your full population, sync a small pilot security group containing only your project team. That lets you confirm records map correctly and catch any issues while the impact is limited to a handful of learners.

Important: If any learner's Microsoft UPN differs from their email address, tell your Arist contact before you sync so records map to the correct person.

  1. Return to Arist with the Global Administrator’s Arist account. Open Organization settings > Delivery methods, expand Microsoft Teams, and confirm Microsoft Teams tenant ID.

  2. For a first-time sync, select Enable automatic user synchronization once. In Additional permissions required, select Continue, sign in to Microsoft with the Global Administrator account for that tenant, and review the User Sync permissions before granting consent.

  3. After consent, choose Sync all Microsoft Teams users or Or select specific groups to synchronize. For an existing sync, keep the saved population unless you intend to change who syncs. If it needs additional metadata permission, follow HRIS Integration - Microsoft Teams for Re-consent.

Choose core learner fields

The Core learner fields section appears once learner sync is enabled and Microsoft consent is granted. It controls which Microsoft Entra property fills each basic learner field. This section is separate from Synced user properties, which requires metadata sync to be enabled for your organization.

The User synchronization panel with the sync population above Core learner fields, showing the Omit names checkbox, the locked Email and Microsoft user ID rows, First name set to Given name, Last name set to Surname and the Add field control, then Synced user properties with the locked Department row

Review how name changes will affect existing learners before choosing the fields.

Important: Turning on Omit names or choosing Leave blank for a name removes the affected names already stored on learners at the next sync, unless they also belong to another organization that keeps those names. Removing an optional field instead stops future syncing and leaves its stored values in place.

Learner field

What you can configure

Email and Microsoft user ID

These mappings are locked.

First name and Last name

Defaults are Given name and Surname. Choose another supported property or Leave blank for either name. Some properties require User.Read.All.

Language

Add it with Add field, then choose Preferred language or a supported extension attribute. This optional row requires User.Read.All.

External user ID

Add it with Add field, then choose Microsoft object ID, Employee ID, or a supported extension attribute. This optional row requires User.Read.All.

Turn on Omit names to stop syncing both first and last names. The name rows become unavailable and display Leave blank. Their individual mappings are kept for when you turn Omit names off.

If User.Read.All has not been granted, Language, External user ID, and Add field are hidden. For the consent steps, see HRIS Integration - Microsoft Teams. If the core fields fail to load, select Try again.

Save and check the sync

  1. Select Save at the bottom of the expanded Microsoft Teams panel.

  2. If Re-sync every user in your tenant? appears, review the scope before selecting Save and re-sync. If Remove stored names? appears, review the effect on existing learners before selecting Save.

  3. After synchronization, confirm the learners appear in the Teams Tenant cohort in Arist. Continue to section 9 to validate Teams installation and access.

To sync additional directory properties into learner metadata, follow HRIS Integration - Microsoft Teams. That guide covers choosing properties, naming destination fields, resolving conflicts, and checking the copied values.

Tip: To add learners immediately, upload a CSV under Cohorts, then Teams Tenant, then Add learners. The live sync then keeps the cohort up to date from there.


9. Validate the rollout

Setup policies do not always propagate consistently across users, even when configured correctly. Validating before go-live prevents a poor first impression for your learners.

  1. Wait 2 to 3 days after installation before validating, since propagation can take up to 72 hours.

  2. In the Teams Admin Center, go to Users, then Manage users.

  3. Pick three to five test users from different departments and hire dates.

  4. For each user, check the Apps tab, where Arist should show as available, and the Policies tab, where the correct policy should be applied.

  5. Ask one test user to open Teams and confirm the Arist app is visible in their sidebar.

  6. If some users do not see the app, a higher-priority policy is overriding it. Add Arist to that policy too.


Related articles

Note: Need help at any point? Reach out to your Arist Customer Success contact, or email [email protected].

Did this answer your question?