IdP Example: Azure Active Directory

In addition to numerous other features, the Azure AD service may also be used as an identity provider (IdP) for single sign-on access to other cloud services, including Skuid. Once you’ve familiarized yourself with the basics of single sign-on (SSO) and Skuid, follow the instructions below to create an SSO configuration for Azure AD.

Warning

Since changing settings within your Azure AD instance can have far-reaching effects on your entire enterprise, Skuid strongly recommends proceeding with the assistance of your resident Azure AD admin.

Note

These instructions apply to the latest, cloud-based version of Azure AD. If using an older instance, such as the desktop interface, you may still be able to follow along, but the specific steps may differ.

SAML Identity and Azure AD Attributes

Before you create the Azure AD SSO configuration, consider which data to use when verifying end users within Skuid—meaning, which attribute element can Azure AD send back that correlates with a field on a Skuid Platform user’s data.

The federation ID field is commonly used for this purpose, but you can also use several other fields. For more information about this, see the information about the SAML Assertion contains Skuid user’s field within the Single Sign-On topic.

With that in mind, here are some of common attributes that Azure AD can send that may relate to your Skuid user’s data:

  • http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
    • Azure AD username, usually an Azure AD email address: e.g. john.doe@example.onmicrosoft.com
  • http://schemas.microsoft.com/identity/claims/displayname
    • Full Name, e.g. John Doe
  • http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname
    • First Name: e.g. John
  • http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname
    • Last Name: e.g. Doe

For more information on Azure AD’s attribute elements, see the Azure AD token reference.

Configuration

Setting up this configuration—like accessing Microsoft’s other cloud services—hinges upon the creation of an app registration within Azure. If you have not already set up an Azure app registration for Skuid, then do so by following the instructions listed in here, alongside Microsoft’s documentation on the subject.

After creating the app registration, you need to do three things:

  1. Obtain the Federation Metadata Document URL and app ID URI from Azure AD
    • The Federation Metadata Document URL provides Skuid all the information it needs to quickly set up an Azure AD SSO configuration.
    • The app ID URI gives Skuid a proper ID for its SSO configuration
  2. Configure an SSO configuration in Skuid using the above URL and URI
    • Creating the SSO configuration generates an Assertion Consumer Service (ACS) URL, which tells the Azure AD app how to send end users back to Skuid after logging in.
  3. Enter the ACS URL as a reply URL for the Azure AD app

The example in this section makes three assumptions:

  1. The Azure AD username attribute should be used to verify users.
  2. Azure AD usernames for this organization match Azure AD email addresses, e.g. john.doe@example.onmicrosoft.com.
  3. Skuid users’ federation IDs should be used to verify Azure AD usernames.

If your organization needs are different than the above, see SAML Identity and Azure AD Attributes for more information.

Metadata URL and App ID URI

In Azure AD

First, locate the Federation Metadata Document URL, which is universal for all app registrations.

Within the Azure AD blade:

  1. Click App registrations.
  2. Click Endpoints.
  3. Copy the Federation Metadata Document URL.

After this, copy the app ID URI for the specific registration created earlier.

  1. Return to the App registrations blade.
  2. Click the specific app registration used for this SSO configuration
  3. Click Properties.
  4. Copy the value within the App ID URI field.

Setting up an SSO configuration

In Skuid

  1. Navigate to Configure > Site > Single-Sign On.
  2. If you haven’t already, click the checkbox next to SAML Enabled.
  3. Click New Single Sign On Config.
  4. Click Import from Identity Provider Metadata File - at URL.
  5. Enter the Federation Metadata Document URL from the previous section.
  6. Click Import.
  7. Click fa-pencil Edit SSO Config to edit the newly-created SSO Config.

From here, fine-tune this SSO configuration to properly send to and accept data from Azure.

  1. Update the following fields:

    • Provider Name: Change the auto-generated name to be something useful to humans, like Azure_AD.

    • Entity (Service Provider Id): Enter the App ID URI from the previous section.

    • SAML Identity is in: An Attribute element

    • SAML Identity contains Skuid User’s: Enter the appropriate Azure AD attribute, as mentioned in the SAML Identity and Azure AD Attributes section.

      For this example, use Federation ID.

  2. Click Save.

ACS URL and Reply URL

In Skuid

Copy down the ACS URL for the newly created SSO configuration.

  1. Click fa-link IDP Configuration Details beside the newly created configuration.

  2. Copy the value of the Assertion Consumer Service (ACS) URL field.

    This value should look something like this:

    https://your-subdomain.skuidsite.com/auth/saml/sp/7f6520a2-3ffa-415d-8632-b16a1da99160/assert

In Azure AD

Within the Azure AD blade:

  1. Click App registrations.
  2. Click the app registration.
  3. Under the Settings blade, click Reply URLs.
  4. Insert the ACS URL from your SSO configuration.
  5. Click Save.

Since this example uses the Federation ID to verify Azure AD attributes against, ensure that that:

  1. Navigate to Configure > Users.

  2. Click fa-pencil Edit Row to edit an SSO user.

  3. Format the user’s Federation ID to match their Azure AD username:

    For this example, assuming the user’s Azure AD username matches their email address, enter the appropriate value, such as john.doe@example.onmicrosoft.com.

  4. Click Save.

To test your SSO configuration, log out of Skuid and proceed to the next section.

Logging in

After completing an Azure AD SSO configuration, the Login with SAML link will appear on your Skuid site’s login page. Click this link to login via Azure AD.

Note

If a Skuid site has more than one SSO configuration, end users will be prompted to choose one when logging in.

Users will be directed to the Microsoft Online login page. During each user’s initial login, they’ll need to give the Azure AD app registration the appropriate permission for SSO logins. This screen will have text similar to the following:

Example-App-Registration needs permission to:

  • Sign you in and read your profile

    You’re signed in as: john.doe@example.onmicrosoft.com

When prompted with the following permission screen, users must click Accept.

Troubleshooting

Most problems with this process arise from a mismatch between what Azure AD sends and how Skuid verifies a SAML identity. If there are errors, review the SAML Identity and Azure AD Attributes section to specifically check:

  • The Identity Location section of your Azure AD SSO configuration:
    • SAML Identity is in must be set to An Attribute element.
    • Attribute Name must match an attribute URL from the Azure AD token reference. These URLs begin with http://schemas.
    • The chosen value SAML Identity contains Skuid User’s must match the Azure AD attribute.

If unsure what information Azure AD is sending when users attempt to login, visit Skuid’s Login History:

  1. Navigate to Configure > Login History.
  2. Look for any attempts that have the SAML Login Type.
  3. Click fa-angle-right View Login Details.

Under the SAML Details section, Skuid displays details of the login attempt listed in JSON format. In particular, verify the attributes values match a Skuid user’s details (such as their federation ID).

There are also several specific errors users may see after attempting to login from the Microsoft Online login page. For the example errors below, replace ... with your Skuid site URL:

  • AADSTS70001: Application with identifier '.../auth/saml/sp/5f6520a2-3ffa-495d-8652-b16a1da95160' was not found in the directory

    The Entity (Service Provider Id) field within the SSO configuration may not be set correctly. Ensure that this value matches the app ID URI from your Azure AD app registration. To review, see the Metadata URL and App ID URI section.

  • AADSTS50011: The reply address '.../auth/saml/sp/5f6520a2-3ffa-495d-8652-b16a1da95160/assert' does not match the reply addresses configured for the application

    The reply URL for your Azure AD app registration may not match the SSO configuration ACS URL on Skuid.

    To verify, check the fa-link IDP Configuration Details for your SSO configuration and ensure that the Assertion Consumer Service (ACS) URL field is present the Azure AD app registrations Reply URLs.

    If you have corrected the Reply URL in Azure AD and are still seeing this error, clear the browser’s cookies and cache.

    To review, see the Reply URL and ACS URL section.