Configuring Microsoft Azure Active Directory using WS-Federation¶

App Builder integrates with Microsoft Azure Active Directory (AD) using the WS-Federation protocol, enabling single sign-on. Each App Builder instance must be individually configured to work with Azure AD and vice versa. There are three main tasks involved:

1. Register App Builder as an Azure AD application
2. Configure Azure AD as an App Builder Security Provider
3. Map App Builder users and groups to Azure identities

Requirements¶

To proceed, you will need the following:

• Administrator access to an Azure account with an Azure Active Directory service
• Administrator access to App Builder
• App Builder must be available via HTTPS with a valid SSL certificate

Properties¶

This document will reference the following properties.

Register App Builder as an Azure AD application¶

The App Builder instance must be registered as Azure AD application. The following page documents the process:

https://docs.microsoft.com/en-us/azure/active-directory/develop/active-directory-integrating-applications

In Short:

1. Log into the Microsoft Azure Portal
2. Navigate to the Azure Active Directory admin center
3. Click on Azure Active Directory from the navigation
4. Click on App Registrations
5. Create a New Registration and provide the Name as App Builder

6. Type in your Redirect URI as https://yourdomainname.com/signin-App Builder (Change 'App Builder' to whatever name you will use within App Builder Security Providers.)

   

7. Click Register

8. Open the newly create Application you registered, and under the Manage side-bar, select Manifest:

   1. Make note of the appId string, such as '"appId": "062e3d2f-c200-40bc-b402-5be728bcdd1a",'
   2. Make note of your primary domain, shown in your AzureAD 'Tenant information.'

   3. Edit the following lines as follows:

      Edit:

      "groupMembershipClaims": null,
          "identifierUris": [],
      

      To be:

      "groupMembershipClaims": "SecurityGroup",
          "identifierUris": [
              "https://[yourprimarydomain.com]/[appId]"
          ],
      

   Example: If primary domain for Azure Tenant is zudy.com:

   

9. Click Save

10. Click on Overview from the navigation
11. Click the Endpoints tab
12. Where it reads Federation metadata document, click on the copy to clipboard icon and paste the value somewhere you can reference later (e.g., Notepad)

Connect and setup new security provider in App Builder¶

In this step you will define the new Security Provider for Azure AD. This includes defining the Type as WS- Federation services, define Audience, MetadataAddress and Wtrealm parameters (provided by Microsoft) and configuring the Claim Types issued from Microsoft to align with any Group mapping inside of App Builder.

1. Navigate to the IDE
2. Select Security Providers
3. Click + User Authentication under User Authentication
4. Select Type as WS-Federation
5. Provide a Name that matches what you used to configure the Redirect URI. For example: Azure

6. Options to change: (Leave as-is for unlisted)

   • Name: ('Azure' in example)
   • Type: WS-Federation
   • Enabled: Yes
   • User Provisioning: Yes ; This will allow Azure to create Users into App Builder.
   • Supplies Group Membership: Yes
   • Store Claims field: Optional ; This allows visibility into the meta claims data coming from Microsoft into an App Builder User.

7. Click Save

8. Note that upon Save App Builder will issue a unique Identifier value for this Provider

Configure the properties parameters¶

In this step you'll configure 3 Parameters that represent values provided from Microsoft Azure.

1. From the Properties panel, create the following claims:

   • Audience: https://**YourAzureprimarydomain.com**/**App-id-from-azure-app-reg**

     Example: https://zudy.com/062e3d2f-c200-40bc-b402-5be728bcdd1r

   • MetadataAddress: https://login.microsoftonline.com/***Your-Tenant-ID***/federationmetadata/2007-06/federationmetadata.xml

   • Wtrealm: https://**YourAzureprimarydomain.com**/**App-id-from-azure-app-reg**

2. Under Claims create the following:

   • Search for the word "groups" and select the first entry that appears which is http://schemas.microsoft.com/ws/2008/06/identity/claims/groups

3. For Usage, select Group

4. Click the checkmark icon to save

Map App Builder users and groups to Azure identities¶

From the Identities area of Secure, you will now see an entry for the Security Provider created. When Users authenticate into App Builder using this Security Provider all of the associated identities will flow through and you'll see records appear in the Provider Groups and Identities by Provider panels accordingly.

From the Provider Groups panel you can provide mappings between any App Builder Groups and Azure Groups that you would like to, using the Groups field. The Groups field here is a drop-down menu listing all Groups configured in App Builder. This will enable just in time provisioning.

With user provisioning¶

If you've enabled user provisioning as described above and attempt to log in, you may be redirected back to the App Builder login. The login form will display a message similar to the following:

The user account (arthur.dent@example.onmicrosoft.com) has not been granted access to an application.

Though App Builder was able to successfully provision the user, the user does not have access to any App Builder applications by default. Assuming the Azure AD user has been added to one or more groups and that Supplies Group Membership is enabled (as described above), you will need to map the Azure AD security groups to App Builder security groups. To do so:

1. Log into App Builder as an Administrator
2. Navigate to the IDE
3. Click the User Management button
4. Click the Identities tab
5. In the Providers panel, highlight your new Azure AD security provider
6. In the Provider Groups panel, click + Group

7. Enter the name of a group you have within AzureAD, along with its Identifier (This can be found by opening a Security Group type within AAD Groups, and making note of its Object Id.)

   Then choose the App Builder group they will be automated added to as a member upon logging in.

8. Click the Save button

Without user provisioning¶

If you have not enabled user provisioning, authentication will have failed with a message similar to the following:

Although you've successfully authenticated with Azure, the account arthur.dent@example.onmicrosoft.com (arthur.dent@example.onmicrosoft.com) is not associated with a local account.

In the message above, "arthur.dent@example.onmicrosoft.com" is the user name (called "name" in claims authentication). The part in parenthesis is the unique identifier (called the "name identifier" in claims authentication). You'll need these two pieces of information for the next step.

1. Log into App Builder as an Administrator
2. Navigate to the IDE
3. Click the User Management button
4. Click the Users tab
5. In the Users panel, select the user would like to map
6. In the Identities panel, click the + Identity button

7. Provide the following:

   • Provider: Provider Name (see above)
   • Name: The Azure user name (see above)
   • Identifier: The Azure user name identifier (see above)

8. Click the Save button.

Sign-out of App Builder

Confirm that now on the Login page there is a "Sign in with …" button that now appears, and it will read the Name you provided when configuring the Security Provider

Example Sign in button for new Security Provider on Login Page

Test logging in, you should be redirected to authenticate with an Azure account