Microsoft Azure Portal Single Sign-On (SSO) integration

This topic contains procedures to configure AppName for Single Sign-On (SSO) in CyberArk Identity using WS-Fed..

With CyberArk Identity, you can choose single-sign-on (SSO) access to the Microsoft Azure Portal web application with IdP-initiated WS-Fed SSO (for SSO access through the Identity User Portal) or SP-initiated WS-Fed SSO (for SSO access through the Microsoft Azure Portal web application), or both. Providing both methods gives you and your users maximum flexibility.

Supported features

This application template supports the following features:

  • SP-initiated SSO

  • IDP-initiated SSO

  • Microsoft WS-Fed user provisioning

  • Role-to-Microsoft 365 License Mapping

Before you begin

Before you configure the Microsoft Azure Portal application for SSO, you need the following:

  • Create a Microsoft 365 account.

  • Create and verify a domain in Microsoft 365.

Prepare Microsoft 365 for single sign-on

This section applies to you if you are creating a new Microsoft 365 account, or if your Microsoft 365 accounts aren’t already federated using ADFS or another identity provider

Before you configure Microsoft 365 for SSO, you need to add your custom domain, get the domain verified, and add your Microsoft 365 user accounts. Use the Microsoft 365 administrative portal to perform these tasks.

Step 1: Create and verify a custom domain for use with Microsoft 365

In order to use SSO with Microsoft 365, you need a unique Microsoft 365 domain. This domain must be an externally accessible domain that resolves to an IP address that belongs to your organization. The IP address must be routable to the server where the you’ve installed the connectors (and the Microsoft Directory Synchronization tool, if you’re still using it). Your Microsoft 365 domain must also be different than the one provided by Microsoft with the onmicrosoft.com domain.

Expect that the process of creating and verifying a domain may take anywhere from a day to a week or so to complete, depending on the time it takes to register a domain with a domain provider, editing the DNS entries to verify ownership, and having Microsoft verify the domain ownership. See the following Microsoft documentation for instructions.

Add and verify your domain:

https://support.office.com/en-za/article/Verify-your-domain-in-Office-365-6383f56d-3d09-4dcb-9b41-b5f5a5efd611?ui=en-US&rs=en-ZA&ad=ZA

Get DNS text records from Microsoft 365 for domain verification:

https://docs.microsoft.com/en-us/microsoft-365/admin/setup/add-domain?redirectSourcePath=%252fen-us%252farticle%252fVerify-your-domain-in-Office-365-6383f56d-3d09-4dcb-9b41-b5f5a5efd611&view=o365-worldwide#add-or-edit-custom-dns-records

Set a default domain:

https://docs.microsoft.com/en-us/microsoft-365/admin/setup/domains-faq?redirectSourcePath=%252fen-us%252farticle%252fChange-your-default-domain-for-email-in-Office-365-1bd69e1c-9598-49ce-b341-9ac895dbe681&view=o365-worldwide.

Set up directory synchronization:

https://support.office.com/en-us/article/Set-up-directory-synchronization-for-Office-365-1b3b5318-6977-42ed-b5c7-96fa74b08846

Configure the AppName application template in the Identity Administration portal

The following procedure describes the steps in the Identity Administration portal needed to configure the AppName application template for SSO.

Step 1: Add the AppName web application template

  1. In the Identity Administration portal, select Apps & Widgets > Web Apps, then click Add Web Apps.

    Add a web app screen

  2. On the Search page, enter the application name in the Search field and click the search button.

  3. Next to the application name, click Add.

  4. On the Add Web App page, click Yes to confirm.

  5. Click Close to exit the Application Catalog.

    The application opens to the Settings page.

Step 2: Configure the Settings page

    Though CyberArk continues to support basic authentication with Microsoft Azure Portal, for various security reasons listed in the Microsoft article https://docs.microsoft.com/en-us/exchange/clients-and-mobile-in-exchange-online/deprecation-of-basic-authentication-exchange-online,CyberArk strongly recommends that you migrate to the more modern and secure token-based authentication.

    The domain that the administrator uses for basic authentication in the Application Settings does not appear in the Microsoft 365 domains list. For basic authentication, use a domain that is different from the one being enabled for SSO with Microsoft Azure Portal.

  1. Select Basic Authentication, then enter the user name and password for your Office 365 administrator account of the default domain <MyCompany>.onmicrosoft.com and click Verify.

  2. CyberArk Identity verifies the credentials and connects to your account.

    Once the verification succeeds, the Application Settings page displays the Office 365 domains section.

  1. Select Token Based Authentication, then copy the following values from the overview page of your registered app in the Azure portal and paste them into the Azure Active Directory Service window in the Identity Administration portal.

    • Application (client) ID
    • Directory (tenant) ID

  2. Enter the client secret that you saved previously.

  3. Click Verify.

  4. (Optional) Select Allow authentication by certificate to enable zero sign-on ("ZSO") for Office 365 on Android and iOS devices.

    The Microsoft Authenticator application is also required for ZSO on Office 365 on iOS devices.

Step 3: Federate your Office 365 domain

  1. Select the domain that you want to federate or take ownership of with CyberArk for Office 365, then click Actions.

    If the domain is in Managed state, you federate it. If the domain is already federated, you take ownership of it and federate it with CyberArk for Office 365. If you change the security certificate used with CyberArk for Office 365, you will need to refederate the domain. Refer to Choose a certificate file for more information about changing the certificate file.

    Taking ownership of a domain is useful in cases where you’ve already federated your account using another system or another instance of the Office 365 + Provisioning application.

    If you have multiple Office 365 domains, you create a separate application in the Identity Administration portal for each domain.

    In the pop-up menu that displays:

    • If you selected a managed domain, click Federate Domain.

    • If you selected a federated domain, click Take Ownership.

    • If you changed the security certificate on the Application Settings page, click Refederate Domain.

      The domain must be owned by the Office 365 application to refederate the domain.

      A message displays that prompts you for confirmation.

  2. Click Yes to continue.

    • If you selected to federate a managed domain, CyberArk Identity changes the selected domain in Office 365 to federated status.
    • If you selected to take ownership of a federated domain, CyberArk Identity changes the selected domain in Office 365 to use your current CyberArk Identity tenant as the identity provider.

    Future logins will be handled by CyberArk Identity.

    If your Office 365 domain was previously federated by using Microsoft DirSync or DirSync and ADFS, then you should go stop those services from running. CyberArk Identity takes ownership of the federated domain, but it doesn’t stop your previous tools, such as DirSync, from running. You must disable DirSync manually, and you may notice synchronization issues if you do not disable DirSync after switching to CyberArk for Office 365 for SSO.

A PowerShell script (O365FederationScript.ps1) is available to view, federate, or unfederate your domain if you are using token-based authentication.

Refer to https://docs.microsoft.com/en-us/microsoft-365/enterprise/connect-to-microsoft-365-powershell?view=o365-worldwide to make sure that your PowerShell environment is properly configured to connect to Office 365.

  1. Select the domain that you want to federate, then click Actions > Download Powershell Script.

  2. Run the downloaded PowerShell script O365FederationScript.ps1, entering R at the security warning to confirm that you want to run the script.

  3. Enter your Office 365 administrator credentials.

    The script presents options to view, federate, or unfederate the domain.

  4. Enter F to federate the domain you selected in the Identity Administration portal.

  5. Run the script again, this time entering V to view the federation settings, confirming success.

Configure the ADFS server

Go to the ADFS server and perform the following steps from PowerShell.

The following steps are applicable for the ADFS version 2012. For other versions, the steps may vary.

Set-MsolADFSContext -Computer <adfs server>

Set-MsolDomainAuthentication -Authentication Managed -DomainName <domain name>

Get-MsolDomain | fl name,status,auth*

Expected values

Variable

Description

adfs server

The computer name of your adfs server.

domain name

Your managed domain name. For example, example.com.

Run the PowerShell script you downloaded in Step 1 to change from managed to federated level.

Step 4: Configure the Permissions page to grant AppName users SSO access

Grant SSO access to AppName by assigning permissions to users, groups, or roles.

  1. On the Permissions page, click Add.

  2. Select the user(s), group(s), or role(s) that you want to grant permissions to, then click Add.

    The added object appears on the Permissions page with View, Run, and Automatically Deploy permissions selected by default.

  3. Select the permissions you want and click Save.

    Default permissions automatically deploy the application to the User Portal if the Show in user app list option is selected on the Settings page. Do not select this option if you intend to use only SP-initiated SSO.

    Change the permissions if you want to add additional control or if you prefer not to automatically deploy the application.

Step 5: Configure the Provisioning page

  1. Select Enable provisioning for this application.

  2. Under Objects to provision, select Enable Hybrid Exchange Support if required.

UnderSync Options, specify how to handle duplicate accounts.

Duplicate accounts are identified when a user account in CyberArk Identity and in the target application have the same email address or Active Directory userPrincipalName.

 

  • Sync (overwrite): Update account information in the target application (this includes removing data if the target account has a value for a user attribute that is not available from CyberArk Identity).

  • Do not sync (no overwrite): Keeps the target user account as it is; CyberArk Identity skips and does not update duplicate user accounts in the target application.

  • Do not de-provision (deactivate or delete): The user's account in the target application is not de-provisioned when a role membership change that would trigger a de-provisioning event occurs.

  • Select Deprovision users in this application when they are disabled in source directory to enable the feature.

    If checked, a user will be deprovisioned when they are marked as disabled in the source directory. Deprovisioning behavior and available deprovisioning options depend on what the target application supports.

  1. Provide necessary role mappings as shown in the image below.


    Microsoft License provisioning might take some time to reflect at the Microsoft 365 portal. SP and IDP authentication will work once the provision is successful and the user has proper licenses.
    You can select Role and ignore license as you can access Microsoft Azure without Microsoft 365 license.

Step 6: Review and save

Review your settings to confirm your configuration. For example, you might want to verify that you selected the appropriate users, groups, or roles on the Permissions page. Click Save when you are satisfied.