You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
title: 'Tutorial: Configure Envoy for automatic user provisioning with Azure Active Directory | Microsoft Docs'
3
-
description: Learn how to configure Azure Active Directory to automatically provision and de-provision user accounts to Envoy.
3
+
description: Learn how to automatically provision and de-provision user accounts from Azure AD to Envoy.
4
4
services: active-directory
5
5
documentationcenter: ''
6
6
author: zchia
7
7
writer: zchia
8
8
manager: beatrizd
9
+
9
10
ms.assetid: na
10
11
ms.service: active-directory
11
12
ms.subservice: saas-app-tutorial
@@ -14,68 +15,70 @@ ms.tgt_pltfrm: na
14
15
ms.devlang: na
15
16
ms.topic: article
16
17
ms.date: 06/3/2019
17
-
ms.author: "jeedes"
18
+
ms.author: Zhchia
18
19
---
19
20
20
21
# Tutorial: Configure Envoy for automatic user provisioning
21
22
22
-
The objective of this tutorial is to demonstrate the steps to be performed in Envoy and Azure Active Directory (Azure AD) to configure Azure AD to automatically provision and de-provision users and/or groups to Envoy.
23
+
This tutorial describes the steps you need to perform in both Envoy and Azure Active Directory (Azure AD) to configure automatic user provisioning. When configured, Azure AD automatically provisions and de-provisions users and groups to [Envoy](https://envoy.com/pricing/) using the Azure AD Provisioning service. For important details on what this service does, how it works, and frequently asked questions, see [Automate user provisioning and deprovisioning to SaaS applications with Azure Active Directory](../manage-apps/user-provisioning.md).
24
+
23
25
24
-
> [!NOTE]
25
-
> This tutorial describes a connector built on top of the Azure AD User Provisioning Service. For important details on what this service does, how it works, and frequently asked questions, see [Automate user provisioning and deprovisioning to SaaS applications with Azure Active Directory](../app-provisioning/user-provisioning.md).
26
-
>
27
-
> This connector is currently in Public Preview. For more information on the general Microsoft Azure terms of use for Preview features, see [Supplemental Terms of Use for Microsoft Azure Previews](https://azure.microsoft.com/support/legal/preview-supplemental-terms/).
26
+
## Capabilities supported
27
+
> [!div class="checklist"]
28
+
> * Create users in Envoy
29
+
> * Remove users in Envoy when they do not require access anymore
30
+
> * Keep user attributes synchronized between Azure AD and Envoy
31
+
> * Provision groups and group memberships in Envoy
32
+
> *[Single sign-on](https://docs.microsoft.com/azure/active-directory/saas-apps/envoy-tutorial) to Envoy (recommended)
28
33
29
34
## Prerequisites
30
35
31
36
The scenario outlined in this tutorial assumes that you already have the following prerequisites:
32
37
33
-
* An Azure AD tenant
34
-
*[An Envoy tenant](https://envoy.com/pricing/)
38
+
*[An Azure AD tenant](https://docs.microsoft.com/azure/active-directory/develop/quickstart-create-new-tenant)
39
+
* A user account in Azure AD with [permission](https://docs.microsoft.com/azure/active-directory/users-groups-roles/directory-assign-admin-roles) to configure provisioning (e.g. Application Administrator, Cloud Application administrator, Application Owner, or Global Administrator).
40
+
*[An Envoy tenant](https://envoy.com/pricing/).
35
41
* A user account in Envoy with Admin permissions.
36
42
37
-
## Add Envoy from the gallery
38
-
39
-
Before configuring Envoy for automatic user provisioning with Azure AD, you need to add Envoy from the Azure AD application gallery to your list of managed SaaS applications.
40
-
41
-
**To add Envoy from the Azure AD application gallery, perform the following steps:**
43
+
## Step 1. Plan your provisioning deployment
44
+
1. Learn about [how the provisioning service works](https://docs.microsoft.com/azure/active-directory/manage-apps/user-provisioning).
45
+
2. Determine who will be in [scope for provisioning](https://docs.microsoft.com/azure/active-directory/manage-apps/define-conditional-rules-for-provisioning-user-accounts).
46
+
3. Determine what data to [map between Azure AD and Envoy](https://docs.microsoft.com/azure/active-directory/manage-apps/customize-application-attributes).
42
47
43
-
1. In the **[Azure portal](https://portal.azure.com)**, in the left navigation panel, select **Azure Active Directory**.
48
+
## Step 2. Configure Envoy to support provisioning with Azure AD
44
49
45
-
50
+
1. Sign in to your [Envoy Admin Console](https://dashboard.envoy.com/login). Click on **Integrations**.
46
51
47
-
2. Go to **Enterprise applications**, and then select **All applications**.
4. Copy the **OAUTH BEARER TOKEN**. This value will be entered in the **Secret Token** field in the provisioning tab of your Envoy application in the Azure portal.
Azure Active Directory uses a concept called *assignments* to determine which users should receive access to selected apps. In the context of automatic user provisioning, only the users and/or groups that have been assigned to an application in Azure AD are synchronized.
66
+
## Step 3. Add Envoy from the Azure AD application gallery
62
67
63
-
Before configuring and enabling automatic user provisioning, you should decide which users and/or groups in Azure AD need access to Envoy. Once decided, you can assign these users and/or groups to Envoy by following the instructions here:
68
+
Add Envoy from the Azure AD application gallery to start managing provisioning to Envoy. If you have previously setup Envoy for SSO you can use the same application. However it is recommended that you create a separate app when testing out the integration initially. Learn more about adding an application from the gallery [here](https://docs.microsoft.com/azure/active-directory/manage-apps/add-gallery-app).
64
69
65
-
*[Assign a user or group to an enterprise app](../manage-apps/assign-user-or-group-access-portal.md)
70
+
## Step 4. Define who will be in scope for provisioning
66
71
67
-
### Important tips for assigning users to Envoy
72
+
The Azure AD provisioning service allows you to scope who will be provisioned based on assignment to the application and or based on attributes of the user / group. If you choose to scope who will be provisioned to your app based on assignment, you can use the following [steps](../manage-apps/assign-user-or-group-access-portal.md) to assign users and groups to the application. If you choose to scope who will be provisioned based solely on attributes of the user or group, you can use a scoping filter as described [here](https://docs.microsoft.com/azure/active-directory/manage-apps/define-conditional-rules-for-provisioning-user-accounts).
68
73
69
-
*It is recommended that a single Azure AD user is assigned to Envoy to test the automatic user provisioning configuration. Additional users and/or groups may be assigned later.
74
+
*When assigning users and groups to Envoy, you must select a role other than **Default Access**. Users with the Default Access role are excluded from provisioning and will be marked as not effectively entitled in the provisioning logs. If the only role available on the application is the default access role, you can [update the application manifest](https://docs.microsoft.com/azure/active-directory/develop/howto-add-app-roles-in-azure-ad-apps) to add additional roles.
70
75
71
-
*When assigning a user to Envoy, you must select any valid application-specific role (if available) in the assignment dialog. Users with the **Default Access** role are excluded from provisioning.
76
+
*Start small. Test with a small set of users and groups before rolling out to everyone. When scope for provisioning is set to assigned users and groups, you can control this by assigning one or two users or groups to the app. When scope is set to all users and groups, you can specify an [attribute based scoping filter](https://docs.microsoft.com/azure/active-directory/manage-apps/define-conditional-rules-for-provisioning-user-accounts).
72
77
73
-
## Configuring automatic user provisioning to Envoy
74
78
75
-
This section guides you through the steps to configure the Azure AD provisioning service to create, update, and disable users and/or groups in Envoy based on user and/or group assignments in Azure AD.
79
+
## Step 5. Configure automatic user provisioning to Envoy
76
80
77
-
> [!TIP]
78
-
> You may also choose to enable SAML-based single sign-on for Envoy, following the instructions provided in the [Envoy single sign-on tutorial](envoy-tutorial.md). Single sign-on can be configured independently of automatic user provisioning, though these two features compliment each other.
81
+
This section guides you through the steps to configure the Azure AD provisioning service to create, update, and disable users and/or groups in TestApp based on user and/or group assignments in Azure AD.
79
82
80
83
### To configure automatic user provisioning for Envoy in Azure AD:
81
84
@@ -95,74 +98,80 @@ This section guides you through the steps to configure the Azure AD provisioning
5. Under the **Admin Credentials** section, input `https://app.envoy.com/scim/v2` in **Tenant URL**. To retrieve the **Secret Token** of your Envoy account, follow the walkthrough as described in Step 6.
101
+
5. Under the **Admin Credentials** section, input `https://app.envoy.com/scim/v2` in **Tenant URL**. Input the **OAUTH BEARER TOKEN** value retrieved earlier in **Secret Token**. Click **Test Connection** to ensure Azure AD can connect to Envoy. If the connection fails, ensure your Envoy account has Admin permissions and try again.
99
102
100
-
6. Sign in to your [Envoy Admin Console](https://dashboard.envoy.com/login). Click on **Integrations**.
7. Upon populating the fields shown in Step 5, click **Test Connection** to ensure Azure AD can connect to Envoy. If the connection fails, ensure your Envoy account has Admin permissions and try again.
8. In the **Notification Email** field, enter the email address of a person or group who should receive the provisioning error notifications and check the checkbox - **Send an email notification when a failure occurs**.
105
+
6. In the **Notification Email** field, enter the email address of a person or group who should receive the provisioning error notifications and select the **Send an email notification when a failure occurs** check box.
10. Under the **Mappings** section, select **Synchronize Azure Active Directory Users to Envoy**.
127
-
128
-
129
-
130
-
11. Review the user attributes that are synchronized from Azure AD to Envoy in the **Attribute Mapping** section. The attributes selected as **Matching** properties are used to match the user accounts in Envoy for update operations. Select the **Save** button to commit any changes.
111
+
8. Under the **Mappings** section, select **Synchronize Azure Active Directory Users to Envoy**.
131
112
132
-
113
+
9. Review the user attributes that are synchronized from Azure AD to Envoy in the **Attribute-Mapping** section. The attributes selected as **Matching** properties are used to match the user accounts in Envoy for update operations. If you choose to change the [matching target attribute](https://docs.microsoft.com/azure/active-directory/manage-apps/customize-application-attributes), you will need to ensure that the Envoy API supports filtering users based on that attribute. Select the **Save** button to commit any changes.
133
114
134
-
12. Under the **Mappings** section, select **Synchronize Azure Active Directory Groups to Envoy**.
115
+
|Attribute|Type|
116
+
|---|---|
117
+
|userName|String|
118
+
|externalId|String|
119
+
|displayName|String|
120
+
|title|String|
121
+
|emails[type eq "work"].value|String|
122
+
|preferredLanguage|String|
123
+
|department|String|
124
+
|addresses[type eq "work"].country|String|
125
+
|addresses[type eq "work"].locality|String|
126
+
|addresses[type eq "work"].region|String|
127
+
|addresses[type eq "work"].postalCode|String|
128
+
|addresses[type eq "work"].formatted|String|
129
+
|addresses[type eq "work"].streetAddress|String|
130
+
|name.givenName|String|
131
+
|name.familyName|String|
132
+
|name.formatted|String|
133
+
|phoneNumbers[type eq "mobile"].value|String|
134
+
|phoneNumbers[type eq "work"].value|String|
135
+
|locale|String|
135
136
136
-
137
+
10. Under the **Mappings** section, select **Synchronize Azure Active Directory Groups to Envoy**.
137
138
138
-
13. Review the group attributes that are synchronized from Azure AD to Envoy in the **AttributeMapping** section. The attributes selected as **Matching** properties are used to match the groups in Envoy for update operations. Select the **Save** button to commit any changes.
139
+
11. Review the group attributes that are synchronized from Azure AD to Envoy in the **Attribute-Mapping** section. The attributes selected as **Matching** properties are used to match the groups in Envoy for update operations. Select the **Save** button to commit any changes.
139
140
140
-
141
-
142
-
14. To configure scoping filters, refer to the following instructions provided in the [Scoping filter tutorial](../app-provisioning/define-conditional-rules-for-provisioning-user-accounts.md).
141
+
|Attribute|Type|
142
+
|---|---|
143
+
|displayName|String|
144
+
|externalId|String|
145
+
|members|Reference|
143
146
144
-
15. To enable the Azure AD provisioning service for Envoy, change the **Provisioning Status** to **On** in the **Settings** section.
147
+
12. To configure scoping filters, refer to the following instructions provided in the [Scoping filter tutorial](../manage-apps/define-conditional-rules-for-provisioning-user-accounts.md).
148
+
149
+
13. To enable the Azure AD provisioning service for Envoy, change the **Provisioning Status** to **On** in the **Settings** section.
145
150
146
151
147
152
148
-
16. Define the users and/or groups that you would like to provision to Envoy by choosing the desired values in **Scope** in the **Settings** section.
153
+
14. Define the users and/or groups that you would like to provision to Envoy by choosing the desired values in **Scope** in the **Settings** section.
This operation starts the initial synchronization of all users and/or groups defined in **Scope** in the **Settings** section. The initial sync takes longer to perform than subsequent syncs, which occur approximately every 40 minutes as long as the Azure AD provisioning service is running. You can use the **Synchronization Details** section to monitor progress and follow links to provisioning activity report, which describes all actions performed by the Azure AD provisioning service on Envoy.
161
+
This operation starts the initial synchronization cycle of all users and groups defined in **Scope** in the **Settings** section. The initial cycle takes longer to perform than subsequent cycles, which occur approximately every 40 minutes as long as the Azure AD provisioning service is running.
162
+
163
+
## Step 6. Monitor your deployment
164
+
Once you've configured provisioning, use the following resources to monitor your deployment:
157
165
158
-
For more information on how to read the Azure AD provisioning logs, see [Reporting on automatic user account provisioning](../app-provisioning/check-status-user-account-provisioning.md).
166
+
* Use the [provisioning logs](https://docs.microsoft.com/azure/active-directory/reports-monitoring/concept-provisioning-logs) to determine which users have been provisioned successfully or unsuccessfully
167
+
* Check the [progress bar](https://docs.microsoft.com/azure/active-directory/manage-apps/application-provisioning-when-will-provisioning-finish-specific-user) to see the status of the provisioning cycle and how close it is to completion
168
+
* If the provisioning configuration seems to be in an unhealthy state, the application will go into quarantine. Learn more about quarantine states [here](https://docs.microsoft.com/azure/active-directory/manage-apps/application-provisioning-quarantine-status).
159
169
160
170
## Additional resources
161
171
162
-
*[Managing user account provisioning for Enterprise Apps](../app-provisioning/configure-automatic-user-provisioning-portal.md)
172
+
*[Managing user account provisioning for Enterprise Apps](../manage-apps/configure-automatic-user-provisioning-portal.md)
163
173
*[What is application access and single sign-on with Azure Active Directory?](../manage-apps/what-is-single-sign-on.md)
164
174
165
175
## Next steps
166
176
167
-
*[Learn how to review logs and get reports on provisioning activity](../app-provisioning/check-status-user-account-provisioning.md)
168
-
177
+
*[Learn how to review logs and get reports on provisioning activity](../manage-apps/check-status-user-account-provisioning.md)
0 commit comments