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
In Advanced Settings, select the Data tab.
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.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.
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.
Workflow tab settings
Select the Workflow tab.
In the Workflow section, set the following Login Screen Options:
Default Workflow
Set to Username | Second Factor.
Public/Private Mode
Set to Public Mode Only.
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.
Multi-Factor Methods tab settings
Select the Multi-Factor Methods tab.
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.
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.
In the Email Settings section, set the following email setting:
Email Field 1
Set to One-Time Passcode via HTML Email.
Post Authentication tab settings
Select the Post Authentication tab.
In the Post Authentication section, set the following:
Authenticated User Redirect
Set to OpenID Connect/OAuth2.
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.
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.
In the OpenID Connect/OAuth 2.0 – Scopes section, for the openid scope, select the Discoverable check box.
In the OpenID Connect/OAuth 2.0 – Clients section, click Add Client.
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.
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.
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
Save your changes.
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.
Save your changes.
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.
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.
Log in to Microsoft Entra admin center (formerly Azure AD portal).
In the left pane, select Azure Active Directory.
In the Security section, click Conditional access.
In the Manage section, click Custom controls (Preview).
Click New custom control.
Enter the JSON for customized controls in the fill-in field.
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.
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.
Log in to Microsoft Entra admin center.
In the left pane, select Azure Active Directory.
In the Security section, click Conditional access.
In the left pane, select Policies.
Click New Policy.
Specify the users, apps, and controls that you want to assign the policy to.
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.
Log in to Microsoft Teams.
Enter your email address.
Enter your password.
Select the two-factor authentication method to use to log in to Microsoft Teams. The following example shows the text message (SMS) method.
On the authentication page, enter the passcode that you received.
The following image is an example.
The following Microsoft Teams page is displayed if the configuration between Microsoft Conditional Access and SecureAuth Identity Platform is successful.
If you do not see this page or if you receive an error message, contact SecureAuth Support.