Integrating with Entra ID (Azure Active Directory)

1. Sign in to Microsoft Entra admin center as Administrator.
2. On the left navigation pane, navigate to Identity > Applications > Enterprise Applications.
3. Click New application, then Create your own application.
4. In the newly opened pane on the right side, name the app "Forecast" and select the option Integrate any other application you don't find in the gallery (Non-gallery).
5. Click the Create button at the bottom of the page (this may take a minute).

Configuring single sign-on and user provisioning

Now that the Forecast app has been added to the gallery, proceed with configuring SSO and user provisioning.

To configure single sign-on

1. In Microsoft Entra admin center, go to the Overview tab and take note of your tenant name, under Basic Information.
2. In the left pane, navigate to Identity > Applications > Enterprise Applications, and select the Forecast app.
3. Go to Properties and set the logo to the image that can be found here.
4. Go to Single sign-on and set it to Linked.
5. Set the Sign-on URL to https://app.forecast.it/azureAD?iss=YOUR_TENANT where YOUR_TENANT corresponds to your tenant name.
6. After the Sign-on URL is input, click Save in the top left.
7. Navigate to Identity > Applications > App registrations, then select the Forecast app.
8. On the Overview page, click the copy icon next to the Application (client) ID and paste it in Forecast, in the Application client id field, in the Entra ID Integration page.
9. In the same Forecast page, enter the tenant name in the Microsoft Entra Tenant field. Keep this page open.
10. In Entra ID, go to Authentication and click Add a platform.
11. Select Web on the right-hand side and under Redirect URI add the following URL: https://graphql.forecast.it/azuread/oauth/
12. Click Configure.
13. Go to Certificates & Secrets.
14. In the Client secrets tab, click New client secret.
15. Under Expires, select 24 months and click Add. The new client's secret should now be listed with a Value.
16. Click the copy icon next to the value and paste it into the Application client secret field in the Entra ID Integration page in Forecast.
17. Go to API Permissions and click Add a permission.
    1. In the newly opened window, click Microsoft Graph, then Delegated permissions.
    2. At the top of the list, expand OpenId permissions, and tick email, OpenID & profile.
    3. Scroll down, expand User, and tick User. Read.
    4. Click Add permissions.
    5. Click Grant admin consent for YOUR_TENANT_NAME, then click Yes.

To configure user provisioning 

1. 1. Navigate to Identity > Applications > Enterprise Applications, and select the Forecast app.
   2. Go to Provisioning and set the Provisioning Mode to 'Automatic'.*
      
      *Warning: If you need to update the integration with a new Microsoft tenant, do not set the provisioning mode to automatic, as it may result in the creation of duplicate team member profiles in Forecast. Please contact Forecast Support before updating the tenant to determine the best way to proceed.
   3. Expand the Admin Credentials section and set the Tenant URL to https://api.forecast.it/scim/v2/ and set the Secret Token to the value of the SCIM bearer token field found in the Forecast Entra ID integration page.
   4. Click Test Connection and Save the configuration if the connection is successful.
   5. Expand the Mappings section and disable Provision Microsoft Entra ID Groups
       by clicking it and clicking the Enabled slider and then the Save button.
   6. Go back to the Provisioning page (use the breadcrumbs at the top of the page).
   7. Expand the Settings section and set the Scope to 'Sync only assigned users and groups'.
   8. At the bottom of the page, click the Provision Status slider so that it is On.
   9. Click Save once again.

Assigning users to Forecast single sign-on in Entra ID

Now that the setup is done, add users to the Entra ID application.

To assign users to Forecast single sign-on in Entra ID

1. Go to Entra ID.
2. Navigate to Identity > Applications > Enterprise Applications.
3. Click on the Forecast app.
4. Under Users and groups, add the needed users.

The added users can now access Forecast through their Microsoft access panel or by clicking the Entra ID logo at the bottom of the Forecast login page.

What Entra ID fields can be provisioned to Forecast?

• "Username principal name" (mandatory) will become the username (local part) of the email address in Forecast.
• "First Name" and "Last Name" will be concatenated into the "Name" field.
• "Account enabled", when ticked off, will become "Active" in Forecast.
• "UserType" will be translated into the permission profile if properly mapped (see next section).

Provisioning permission profiles from Entra ID

By default, all Entra ID users will be provisioned with the 'Collaborator' permission profile in Forecast. However, you can configure Entra ID to provision user types, which will be translated into Forecast permission profiles.

We recommend using Entra ID's App Roles for this purpose. This can be done by adding an expression mapping targeting the userType attribute with a source of "SingleAppRoleAssignment([appRoleAssignments])".

Here are the steps in detail:

To provision permission profiles from Entra ID

1. Create app roles

1. Sign in to the Entra ID.
2. Navigate to Identity > Applications > App registrations > Forecast > App roles, and click Create app role.
3. Enter a Display Name, a Value, and a Description for the app role. The Display Name must match the permission profile name in Forecast (not case sensitive), as this is the attribute that will be passed on to Forecast.
4. Select Both (Users/Groups + Applications) for Allowed member types and tick the box under Do you want to enable this app role.
5. Click Apply.
6. Repeat the procedure so as to get one app role for each of your Forecast permission profiles.

2. Grant API permissions to the app roles

1. Navigate to App registrations > Forecast > API permissions.
2. Click Add a permission, then navigate to My API > Forecast > Application Permissions.
3. Tick the Permission box for all the app roles you created and click Add permissions.

3. Map the attributes

1. Navigate to Identity > Applications > Enterprise applications > Forecast > Provisioning > Attribute mapping > Provision Microsoft Entra ID Users, and click Add new mapping (at the bottom).
2. Set the Mapping type to 'Expression'.
3. In Expression, enter this expression: SingleAppRoleAssignment([appRoleAssignments])
4. In Default value if null (optional): enter the default Forecast permission profile for users with no Entra ID app role assigned. If this field is left blank, the default permission profile will be 'Collaborator'.
5. Target attribute: select 'userType'
6. Match objects using this attribute: No.
7. Apply this mapping: Always.
8. Click the OK button.

The role assigned to a user in Entra ID will be translated to the corresponding permission profile in Forecast by matching the permission profile name with the Entra ID user type (mapped to app roles). This means that if you assign an Entra ID user a role of "Admin", they will be provisioned with an Admin permission profile in Forecast. If Forecast does not find a match, it will default to the profile ‘Collaborator’ (unless you modify the 'Default value if null' in the mapping of the userType).

Managing authentication types

When enabling an SSO integration in Forecast, the default setting Require SSO is not enabled. If SSO is enabled but not required, users may login using SSO or standard authentication (username/password combination). If Require SSO is enabled, SSO is required for login and standard authentication will not work. It is possible to set exceptions to the SSO requirement, if desired. 

To enable Require SSO

1. Click Admin in the top bar. 
2. Select Integrations from the dropdown. 
3. Scroll to Security & single sign-on (SSO).
4. Toggle to enable.
5. Select any users exempt from the SSO requirement for login, as needed. 
6. A list of exempt users displays below the dropdown. 

Related articles

Supported SCIM fields for User Provisioning

What will happen in Forecast if a provisioned user is removed from the app in Entra ID?