Skip to main content

Microsoft Conditional Access Custom Controls integration guide

Microsoft Conditional Access is a feature of their Microsoft Entra ID (formerly Azure AD) service. This feature allows organizations to define and enforce policies that evaluate the conditions under which a user is allowed to access company resources. This ensures that access is only granted under the right conditions and to the right people.

Microsoft has 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 Microsoft Entra ID customer to call out to the third party's authorization process.

Note

For the Microsoft External Access Method (EAM) integration in the Identity Platform, see Microsoft Conditional Access External Authentication Method (EAM) integration guide.

Process

To set up a Conditional Access integration in the Identity Platform, the following is an outline of tasks to complete.

Applies to

Applies to the following Identity Platform releases and hotfixes:

  • Identity Platform 24.04

  • Identity Platform 23.07, requires hotfix 23.07-1 or later

  • Identity Platform 22.12, requires hotfix 22.12-4 or later

Have a configured OIDC application

Have an OpenID Connect (OIDC) application for the Conditional Access configuration. See Configure OIDC application.

Contact Support to configure the Conditional Access integration

After you've configured an OIDC application, contact Support and open a support ticket with "Conditional Access" in the subject line. Provide the first two items:

  • Client ID. In the Advanced Settings > Post Authentication tab for the OIDC application, copy and provide the Client ID.

  • Public URL. In the Advanced Settings > Post Authentication tab for the OIDC application, copy and provide the public URL of the OIDC application.

  • Then, you will receive a JSON file from Support. You will need this for the task in Configure Microsoft Custom Control.

Configure OIDC application

In the Identity Platform, have an OIDC application configured for use with Microsoft Conditional Access.

The Identity Platform with this hotfix will 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). The Identity Platform must obtain that information and validate the JSON Web Token (JWT).

For the OIDC application, configure the settings as described next in each of the sub sections.

Test connection

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

Data tab settings

  1. In Advanced Settings, select the Data tab.

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

    Make sure the searchFilter field is set to (|(samAccountName=%v)(userPrincipalName=%v)) to allow to allow this application a dual lookup filter to support the UPN format provided by the inbound Microsoft request.

    ms_conditional_data.png

  3. In the Profile Fields section, set the following Aux ID value:

    Aux ID 2

    Set to otherLoginWorkstations.

    You will need this on the Post Authentication tab for the Consent Storage Attribute field.

    ms_conditional_auxid2.png

  4. In the Global Aux Fields section, set the following Global Aux ID value:

    Global Aux ID 1

    Set to Validated.

    You will need to set this Aux ID on the Post Authentication tab for the Custom Claims.

    ms_conditional_globalauxid.png

Workflow tab settings

  1. Select the Workflow tab.

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

    ms_conditional_workflow01.png

    Default Workflow

    Set to Username | Second Factor.

    Public/Private Mode

    Set to Public Mode Only.

  3. In the Customer Identity Consumer section, set the following values:

    Receive Token

    Set to Token.

    Conditional Access

    Set to True.

    Leave all other fields set to the default.

    ms_conditional_workflow02.png

Multi-Factor Methods tab settings

  1. Select the Multi-Factor Methods tab.

  2. In the Multi-Factor Configuration section, configure the multi-factor methods that you want to enable in the Phone Settings.

    For example, set the following phone (SMS) and email methods.

    ms_conditional_mfa01.png

    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.

  3. In the Email Settings section, set the following email setting:

    Email Field 1

    Set to One-Time Passcode via HTML Email.

    ms_conditional_mfa02.png

Post Authentication tab settings

  1. Select the Post Authentication tab.

  2. In the Post Authentication section, set the following:

    Authenticated User Redirect

    Set to OpenID Connect/OAuth2.

    ms_conditional_post-auth01.png

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

    User ID Mapping

    Set to Authenticated User ID.

    Name ID Format

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

    Encode to Base64

    Set to False.

    ms_conditional_post-auth02.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 instance.

    For example, idp.company.com.

    This must be a public-facing and have a valid SSL certificate.

    Signing Algorithm

    Set to one of the following values:

    • 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 earlier on the Data tab to a string attribute.

    For example, otherLoginWorkstations.

    Authorization Code Lifetime

    Access Token Lifetime

    Refresh Token Lifetime

    Leave the default settings as is.

    ms_conditional_post-auth03.png

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

    ms_conditional_post-auth04.png

  6. In the OpenID Connect/OAuth 2.0 – Clients section, click Add Client.

    ms_conditional_post-auth05.png

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

      Enabled

      Set to True.

      Name

      Set a name like ConditionalAccess.

      Client ID

      Client ID is automatically created.

      Client Secret

      Client Secret is automatically created.

      JSON Web Encryption

      Set to Disabled.

      JSON Web Key URI

      Clear the text box and leave blank.

      ms_conditional_post-auth06.png

    2. 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.

    3. In the OpenID Connect/OAuth 2.0 - Client Redirect URIs section, click Add Redirect URI and set the following:

      URI

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

      ms_conditional_post-auth07.png

  7. Save your changes.

  8. In the OpenID Connect Access / ID Token Claims section, set the following values:

    Sub

    Set the Profile Property to Conditional access session value.

    Discoverable

    Select this check box.

    ms_conditional_post-auth09.png

  9. Save your changes.

  10. In the OpenID Connect ID Token Custom Claims section, click Add Custom Claim and set the following values:

    Claim

    Set to SecureAuthMFA.

    Profile Property

    Set to Global Aux ID 1.

    This is the Global Aux ID that you set to Validated on the Data tab.

    Discoverable

    Select this check box.

    ms_conditional_post-auth08.png

Configure Microsoft Custom Control

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

Note

Microsoft changed the name from Azure AD to Microsoft Entra ID. The configuration screenshots may be out of date, but the process should be similar.

  1. Log in to Microsoft Entra admin center (formerly Azure AD portal).

  2. In the left pane, select Azure Active Directory.

  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.

    If you did not already request this information, see the Process about contacting Support.

    In the JSON file, set the following configurations:

    AppId

    Set to the data application referenced by Microsoft.

    ClientId

    Copy and paste the ClientID from the Post Authentication tab > OpenID Connect/OAuth 2.0 - Clients section in Step 6.

    DiscoveryUrl

    Set to the OpenID configuration for the designated OIDC applicationi.

    52333786.png

    For your convenience, you can copy the following code snippet into the JSON file and change the values as needed.

    {   
    "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 Conditional Access policy

Create a Microsoft Conditional Access policy.

Note

Microsoft changed the name from Azure AD to Microsoft Entra ID. The configuration screenshots may be out of date, but the process should be similar.

  1. Log in to Microsoft Entra admin center.

  2. In the left pane, select Azure Active Directory.

  3. In the Security section, click Conditional access.

  4. In the left pane, select Policies.

  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 the 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: