Skip to main content

Microsoft Conditional Access Custom Controls integration guide

Microsoft has a feature in their Azure stack called Conditional Access. This feature allows Azure customers to apply policies to either the login process to Office 365 or specific apps and tiles within Office 365/Azure. Using this feature, Azure customers can restrict access to applications, such as Outlook, SharePoint, and others, based on several different factors.

Recently, Microsoft added a function to Conditional Access called custom controls. Custom controls allow third-party integration into Conditional Access. This process involves having a registered application by the third party to be allowed globally by Microsoft and then providing OpenID Connect (OIDC) endpoints for use by the Azure customer to call out to the third party's authorization process.

Audience

This guide is intended for administrators who need to install and configure Microsoft Conditional Access for use with SecureAuth® Identity Platform.

Prerequisites

You must ensure that you have the following items:

  • Install Identity Platform release 9.2 or later and configure one or more realms for that appliance

  • Configure the following tabs in Advanced Settings (formerly Classic Experience) of the SecureAuth Web Admin console before configuring any other tabs:

    • Overview: Define the description of the realm and SMTP connections.

    • Data: An enterprise directory must be integrated with SecureAuth Identity Platform.

    • Workflow: Define how users access the target.

    • Multi-Factor Methods: Define the Multi-Factor Authentication methods that are used to access the target, if any.

  • Gain administrative access for Microsoft Azure.

  • Install and configure Internet Information Services (IIS) for Windows Server.

  • Set up Modern Authentication in your server environment. For more information, see the Hybrid Modern Authentication overview and prerequisites for using it with on-premises Skype for Business and Exchange servers article on the Microsoft website.

  • Contact Support, and open a support ticket titled "Tailoring - Conditional Access." Request the following items so you have them on hand during the configuration:

SecureAuth Identity Platform configuration steps

In Advanced Settings, create a realm and configure it for use with Microsoft Conditional Access.

Configure Internet Information Server (IIS) for Windows Server

  1. Log in to your SecureAuth Identity Platform Admin console.

  2. Create a new OIDC realm for conditional access configuration.

  3. Add the client and save your configuration.

    Once saved, the server will generate the Client ID and Client Secret.

  4. Copy the Client ID to include in the support ticket.

  5. Open a ticket with Support. In this ticket, provide the following information:

    • Email subject line/title of ticketTitle: Tailoring Request – Configure Conditional Access

    • Provide the full URL for the new Conditional Access realm

    • Provide the Client ID captured above.

  6. When you receive the JSON file from Support in the ticket, copy the ASPX and code-behind pages under the root of the newly-defined realm. This is located in D:\SecureAuth\SecureAuth Realm_number. For example, D:\SecureAuth\SecureAuth5.

    A custom pre-authentication page is used to retrieve the user ID from Microsoft for this request. Microsoft sends a HTTP POST with the OIDC parameters and an additional parameter called id_token_hint. This parameter includes a JSON web token (JWT) and a number of claims, including the unique ID for the user and their user principal name (UPN). SecureAuth Identity Platform must obtain that information and validate the JWT.

Create an inbound rule for Conditional Access

Using the IIS Manager, create an inbound rule for Conditional Access in this new realm.

  1. On the Start menu, click Run.

  2. In the Open dialog box, type inetmgr, and click OK.

  3. In IIS, select Default Web Site, expand the list, and select the newly created Conditional Access realm.

  4. In the Features View, click URL Rewrite.

  5. Set an inbound rewrite rule under the realm folder. For example, SecureAuth3.

    arculix_ms_cond_access_edit_inbound_rule.png

    The URL rewrite rule, shown in the following image, captures requests and places them on the custom page to decode the JWT that Microsoft sends over VIA POST.

    arculix_ms_cond_access_edit_inbound_rule_2.png

    Note

    For more information about the URL rewrite rule, see the Creating Rewrite Rules for the URL Rewrite Module article on the Microsoft website.

Change the query string setting

Using the IIS Manager, change the query string setting for the SecureAuth realm number. For example, SecureAuth3.

  1. In the IIS Manager, focus on the appropriate realm.

  2. Right-click Request Filtering and select Open Feature.

  3. Select the Query Strings tab.

  4. On the right side of the page, click Edit Feature Settings.

  5. In the Request Limits section, set the following:

    Maximum URL length (Bytes)

    Set to 6144.

    Maximum query string (Bytes)

    Set to 4096.

    MSconditional_edit_filtering.png

  6. Click OK to save the changes.

  7. Ensure that https://login.microsoftonline.com/common/discovery/keys is accessible from the SecureAuth server.

Data tab settings

  1. Select the Data tab.

  2. Create a connection based on the data store type, such as Active Directory or SQL Server.

    MSconditional_connect_settings.png

  3. In the Profile Fields section, set the following auxiliary values:

    Aux ID 2

    Set to otherLoginWorkstations.

    Aux ID 5

    Set to otherIpPhone and select the writable checkbox.

    This field is set from the custom pre-authentication page – MSConditionalAccess.aspx.vb.

    MSconditional_aux.png

  4. In the Global Aux Fields section, set Global Aux ID 1 to Validated.

    47238998.png

Workflow tab settings

  1. Select the Workflow tab.

  2. In the Login Screen Options section, set the following values:

    Default Workflow

    Set to Username | Second Factor.

    Public/Private Mode

    Set to Public Mode Only.

    47238999.png

  3. In the Customer Identity Consumer section, set Receive Token to Token.

    Leave all other fields set to the default.

    47239000.png

Multi-Factor Methods tab settings

  1. Select the Multi-Factor Methods tab.

  2. In the Phone Settings section, configure the Multi-Factor Authentication methods that you want enabled.

    The following example shows how to set the email and text (SMS) methods:

    Phone Field 1

    Set to One-Time Passcode via Phone Call and SMS.

    Phone Field 2

    Set to One-Time Passcode via Phone Call and SMS.

    47239001.png

  3. In the Email Settings section, set Email Field 1 to One-Time Passcode via HTML Email.

    47239002.png

Post Authentication tab settings

  1. Select the Post Authentication tab.

  2. In the Post Authentication section, set Authenticated User Redirect to OpenID Connect/OAuth2.

  3. In the User ID Mapping section, set the following values:

    User ID Mapping

    Set to Authenticated User ID.

    Map other parameters, if needed.

    Name ID Format

    Set to urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified.

    Encode to Base64

    Set to False.

    47239003.png

  4. In the OpenID Connect/OAuth 2.0 – Settings section, set the following values:

    Enabled

    Set to True.

    Issuer

    Set to the fully qualified domain name (FQDN)/Hostname of the IdP appliance. For example, idp.company.com.

    This must be publicly facing and have a valid SSL certificate.

    Signing Algorithm

    Set to one of:

    RSA SHA256 (RS256)

    An asymmetric algorithm, which means it uses a public/private key pair. SecureAuth uses the private key for signing and provides you with the public key to use to validate the signature.

    HMAC SHA256 (HS256)

    A symmetric algorithm, which means one secret key is shared between SecureAuth and the end-user. The same key is used to create the signature and to validate it. This key must be kept secret at all times.

    Signing Cert

    Set to any certificate that is a private key readable by SecureAuth Identity Platform.

    Do not use wild cards in a certificate.

    Auto Accept User Consent

    Set to True to provide a clean user experience.

    Enable User Consent Storage

    Set to True to provide a clean user experience and to enable check session endpoints.

    Consent Storage Attribute

    Set to the AUX ID 2 value that was mapped to a string attribute. For example, otherLoginWorkstations.

    Authorization Code Lifetime

    Access Token Lifetime

    Refresh Token Lifetime

    Leave set to the default.

    47239004.png

  5. In the OpenID Connect/OAuth 2.0 – Scopes section, select the Discoverable check box for the openid scope.

    47239005.png

  6. In the OpenID Connect/OAuth 2.0 – Clients section, click Add Client and set the following values:

    Name

    Set to ConditionalAccess or another appropriate name.

    Client ID

    Set to the appropriate client ID for this client.

    Enabled/Disabled

    Select the check box.

    47239006.png

  7. In the OpenID Connect/OAuth 2.0 - Client Details section, set the following values:

    Enabled

    Set to True.

    Name

    Set to ConditionalAccess or another appropriate name.

    JSON Web Encryption

    Set to Disabled.

    JSON Web Key URI

    Clear the text box and leave blank.

    47239007.png

  8. In the Allowed Flows section, set the following values:

    Authorization Code

    Set to True.

    Implicit

    Set to True.

    Hybrid

    Set to False.

    Client Credentials

    Set to False.

    Resource Owner

    Set to False.

    Refresh Token

    Set to True.

    Introspection

    Set to True.

    Revocation

    Set to True.

    47239008.png

  9. In the OpenID Connect/OAuth 2.0 - Client Redirect URIs section, click Add Redirect URI then set the Client Redirect URI to:

    https://login.microsoftonline.com/common/federation/OAuth2ClaimsProvider

    arculix_ms_cond_access_client_scope_restrictions.png

  10. In the OpenID Connect/OAuth 2.0 – Claims section, set the following values:

    Sub

    Set to AUX ID 5, which was mapped to the otherIpPhone value on the Data tab.

    Discoverable

    Select the check box.

    47239010.png

  11. In the OpenID Connect/OAuth 2.0 – Custom Claims section, click Add Custom Claim and set the following values:

    Claim

    Set to SecureAuthMFA.

    Profile Property

    Set to Global Aux ID 1.

    Discoverable

    Select the check box.

    47239011.png

System Info tab settings

  1. Select the System Info tab.

  2. In the Links section at the bottom of the screen, click Click to edit Web Config file to edit the web.config file.

  3. Add the following key(s) to the <appSettings> section:

    <add key="MSConditionalAccess-ProfileField" value="AuxID5" />

    Note

    The following keys are required only if user profile data is using samAccountName as uniqueidentifier. The keys are required to create a separate API realm. (Do not use an OpenID Connect realm as an API realm because you cannot have two different settings for an OpenID Connect realm.) After adding the following keys, see Optional API realm configuration.

    <add key="MSConditionalAccess-EnableUPNsamAccountNameConversion" value="True" />
<add key="MSConditionalAccess-UPNsamAccountNameConversionUsingAPI" value="False" />
<add key="MSConditionalAccess-API-SecureAuthRealmUrl" value="https://<domain or localhost>/SecureAuthXX" />
<add key="MSConditionalAccess-API-AppId" value="XXXXXXXXXXXX" />
<add key="MSConditionalAccess-API-AppKey" value="XXXXXXXXXXXXXXXXXXXXX" />
<add key="MSConditionalAccess-API-samAccountNameField" value="AuxID6" />

  4. Save all changes made to this configuration and exit.

Optional API realm configuration

The following steps are required if user profile data is using samAccountName as uniqueidentifier and you set the additional keys in the System Info tab setting section.

System Info tab settings

  1. Select the System Info tab.

  2. In the Links section at the bottom of the screen, click Click to edit Web Config file to edit the web.config file.

  3. In the <appSettings> section, change the value of the following key to "True":

    <add key="MSConditionalAccess-UPNsamAccountNameConversionUsingAPI" value="True" />

Data Tab settings

  1. Select the Data tab.

  2. Create a connection based on the data store type, such as Active Directory or SQL Server.

    47246883.png

  3. In the Search Filter section, set the following:

    Search Attribute

    Set to userPrincipalName,

    searchFilter

    Set to (&(userPrincipalName=%v)(objectclass=*)) .

    ms_cond_access_search_filter.png

  4. In the Profile Fields section, set Aux ID 6 to sAMAccountName.

    This field is set to match the MSConditionalAccess key you set in the System Info tab setting section.

    76644608.png

  5. Save your changes.

Enable the API

  1. Select the API tab.

  2. In the API Key section, select the Enable API for this realm check box.

  3. In the API Permissions > Authentication section, select the Enable Authentication API check box.

  4. In the Identity Management section, select the User Management - add / update / retrieve users and their properties. check box.

    76644654.png

  5. Save your changes.

Configure Microsoft Custom Control

Create and configure a new custom control for Microsoft Conditional Access.

  1. Log in to Microsoft Azure.

  2. Select Azure Active Directory in the left pane.

  3. In the Security section, click Conditional access.

  4. In the Manage section, click Custom controls (Preview).

  5. Click New custom control.

  6. Enter the JSON for customized controls in the fill-in field.

    MSconditional_controls.png

  7. Enter the JSON provided by SecureAuth Support, then click Save. Contact SecureAuth Support per the Prerequisites steps, if you did not already request this information.

    In the JSON file, set the following configurations:

    AppId

    Set to the data application referenced by Microsoft.

    ClientId

    Set to the designated realm located in the OpenID Connect/OAuth 2.0 - Clients section of the Post Authentication tab.

    DiscoveryUrl

    Set to the OpenID configuration for the designated realm.

    52333786.png

    For your convenience, copy the following code snippet into the JSON file and change values appropriately:

    {   
    "Name": "Name for SecureAuth MFA",   
    "AppId": "Microsoft data App ID",   
    "ClientId": "SecureAuth ClientID",   
    "DiscoveryUrl": " https://SecureAuthURL/secureauthXX/.well-known/openid-configuration ",   
    "Controls":    
        [       
            {           
                "Id": "SecureAuthIdP",           
                "Name": "SecureAuthIdP",           
                "ClaimsRequested":           
                    [                         
                        {                
                            "Type": "SecureAuthMFA",                
                            "Value": "Validated",                
                            "Values": null              
                        }           
                    ]       
            }   
        ]
}

Create a Policy

Create a Microsoft Conditional Access policy.

  1. Log in to Microsoft Azure.

  2. Select Azure Active Directory in the left pane.

  3. In the Security section, click Conditional access.

  4. Select Policies in the left pane.

  5. Click New Policy.

    MSconditional_add_policies.png

  6. Specify the users, apps, and controls that you want to assign the policy to.

    47239015.png

  7. Save your changes.

Test Microsoft Conditional Access with SecureAuth Identity Platform

Test that Microsoft Conditional Access works with the Identity Platform. In this scenario, you will test with Microsoft Teams, but you could also test with Outlook or Skype for Business.

  1. Log in to Microsoft Teams.

  2. Enter your email address.

    47246887.png

  3. Enter your password.

    47246886.png

  4. Select the two-factor authentication method to use to log in to Microsoft Teams. The following example shows the text message (SMS) method.

    47246884.png

  5. On the authentication page, enter the passcode that you received.

    The following image is an example.

    47246885.png

  6. The following Microsoft Teams page is displayed if the configuration between Microsoft Conditional Access and SecureAuth Identity Platform is successful.

    47246888.png

    If you do not see this page or if you receive an error message, contact SecureAuth Support.

In this section: