Workspace ONE - AirWatch Provisioning App

The AirWatch Provisioning App within Workspace ONE is still relatively new and although it has it quirks, it can still be useful in certain use cases.

So what is the AirWatch Provisioning App used for?

The app is designed for the use cases where there is no on premise ldap server that can be used with the Workspace ONE UEM Cloud Connector to synchronize users.  This app can be used when users are created in Workspace ONE Identity via SCIM or JIT. Workspace ONE Identity will then create the users in Workspace ONE UEM.

Lets first discuss some important information about using the AirWatch Provisioning App in Workspace ONE:

• Currently, Workspace ONE will only provision at the top level (Customer) Organization Group (OG) in Workspace UEM.
• An LDAP Server can NOT be configured at the top level OG in Workspace ONE UEM (unless the users exist in the directory that will be created - but if this is the case, you shouldn't be using the provisioning adapter)
• Workspace ONE Identity needs to be configured as a SAML Provider at the top level OG.
• If you are using JIT to create users in Workspace ONE Identity, you MUST send a valid GUID to Workspace ONE has part of the SAML attributes. This is required if you plan on using the Workspace ONE Hub native application to enroll your device. This GUID will be mapped to the External ID and provisioned to Workspace ONE UEM. See  https://www.uuidgenerator.net/ as an example.
• If you are using JIT to create users in Workspace ONE Identity, you need to use a web browser to log into Workspace ONE initially before using the Workspace ONE Hub native app. This limitation is because the user needs to exist in UEM at the time of enrollment.

Step 1: Export your Workspace ONE IDP Metadata

1. Log into Workspace ONE Identity and go to Catalog -> Settings
2. Click on SAML Metadata
3. Download your "Identity Provider (IdP) metadata"
   

Step 2: Configure UEM to use SAML Authentication

1. Log into Workspace ONE UEM
2. Go to Group & Settings -> All Settings -> System -> Enterprise Integration -> Directory Services
3. Ensure Directory Type is set to "None"
4. Enable "Use SAML for Authentication"
5. Under Enable SAML Authentication for*, check Self-Service Portal and Enrollment.
6. Enable "Use New SAML Authentication Endpoint"
   
   Note: This step might be a bit confusing as to why we have to configure UEM in this manner. It was confusing to me at first.  The provisioning adapter in Workspace ONE Identity will leverage the REST API to create accounts in UEM. To create user accounts in UEM (of Directory Type), it requires that either a Directory is configured or SAML is enabled. As mentioned earlier, we can not enable a directory so we essentially have to configure SAML. 
   
   
   
7. In the SAML 2.0 section, click upload to Import Identity Provider Settings
8. Select the metadata you downloaded in Step 1.
9. Scroll down and click save.

Step 3: Add AirWatch Provision App in Workspace ONE Identity

1. In Workspace ONE Identity, go to Catalog-> New
2. Browse from the Catalog and select "AirWatch Provisioning"
   
3. Click Next
4. Edit the Single Sign-On URL and Recipient URL with your UEM server
   
5. Keep the "default_access_policy_set" and Click Next
6. Click Save
   
7. Select the AirWatch Provisioning App and Click Edit
   
8. Click Next
9. On the Configuration Tab, enable "Setup Provisioning"
   
10. Click Next
11. Enter your AirWatch Device Services URL
12. Enter your Admin Username
13. Enter your Admin Password
    Note: Whenever you edit this application be very careful of Chrome's password auto-fill. It will update the password if you have one saved in chrome. After you hit test connection it will revert back to your saved password in Chrome.
14. Enter your AirWatch API Key
    Note: If you don't have an API Key, in UEM, go to Groups & Settings -> All Settings -> System -> Advanced -> API -> REST API
    Click Override -> Add
    Provide a Service Name with the account type of Admin.  Copy the API Key.
15. Enter your top level OG Group ID
16. Click Test Connection and validate connectivity.
17. Click Enable Provisioning
    
18. Verify the mapping are correct. If you are using JIT, make sure all these attributes have come over in the SAML assertion.
    
19. Under Group Provisioning, add any groups you want to provision to UEM.
    
20. Click Next
21. Click Save

Note: If you get an error when saving, please see the note earlier about chrome's auto password fill.

Step 4: Entitle Users to the AirWatch Provisioning App

You have the option of entitling users individually or using a group. If you are using JIT you might want to consider using a dynamic group.

1. Click the Assign button on the AirWatch Provisioning App
2. Search for the user and/or group
3. Under "Deployment Type" you MUST Select Automatic. If you leave the default "User Activated" it will never get provisioned to the user.

Step 5: Create a Dynamic Group (Optional)

If you are using JIT to create users into Workspace ONE, it easier to create a dynamic group and assign that group to the provisioning adapter.

1. Click on "Users & Groups"
2. Click on Groups
3. Click Add Group
4. Provide a group name and Click Next
5. Do not select any users and Click Next
6. Under Group Rules, you can either choose based on the JIT Directory that was created or the domain you chose for the JIT Users
   
7. Click Next
8. Click Next to exclude users
9. Click Create Group

Troubleshooting

1. If you receive the error "Error not provisioned" in the assignment screen and you hover over the error message and see "Failed to validate attributes while trying to provision user" this means that the values for the attributes you used in Attribute Mappings of the provisioning adapter configuration are either null or missing. Please make sure you create the user in Workspace ONE Identity with all the necessary attributes to create the account in Workspace ONE UEM. This includes the External ID. Please see the note at the beginning of the blog regarding the External ID
   
2. While trying to enroll your device with the HUB application application you receive a generic error like "An Error has occurred". See the note about External ID.
3. When trying to provision the Mobile SSO profile you receive an error that the PrincipalName contains an invalid value.
   
   This means that you have probably created the Workspace ONE UEM account with an email as the Username. When the Mobile SSO certificate payload was created, it uses the username as the principal name on the certificate. Unfortunately you can not have the "@" character in the principle name. You have two choices to resolve this issue:
   a) In the AIrWatch Provisioning Adapter mappings, use another attribute to represent the username that does not contain the @ sign. You might need to adjust the values being imported into Workspace ONE identity (whether by JIT or via the connector). Please make sure the username and the prefix of the UPN remain the same.
   b) Use a lookup in Workspace ONE UEM to parse the prefix of the email address and use that in the certificate payload:
   Group & Settings -> All Settings -> Devices & Users -> General -> Lookup Fields
   Add Custom Field
   Create a Name such as EmailNickName and use a regex such as ".+?(?=@)"
   
   You can then use "EmailNickName" in your Certificate Payload