Azure

Preparing Active Directory for federation

When you configure federation, your local Active Directory (AD) users should be provisioned to Azure AD. You can do this by using synchronization tools like Azure AD Connect.

The following installation steps are provided for a configuration where the objectGUID attribute is selected for ImmutableID. If you’re using different attribute for this purpose, such as msDS-ConsistencyGuid, ensure to align it accordingly.

Before configuring synchronization, you might need to prepare your local AD, including:

  • Configuring UPN suffix for non-routable domain names

  • Cleaning up AD objects

  • Planning filters for AD users

  • Planning for multiple forests

To simplify your configuration, Microsoft provides Azure AD Connect, which will automate many of the required steps. You can download Azure AD Connect at Microsoft Azure Active Directory Connect.

Azure AD Connect automatically configures your Azure AD domain and exports a configuration file that provides the settings needed to complete the federated single sign-on connection from PingFederate. If you’re using Azure AD Connect and have the configuration file, proceed to install and configure PingFederate to complete your setup.

Configuring a federated domain

Add a new federated domain for your account.

About this task

After signing up for Office 365, the only domain associated with your account is the onmicrosoft.com subdomain chosen during registration, such as contoso.onmicrosoft.com. To enable single sign-on (SSO) to Azure AD and Office 365, you should have another domain added to the environment.

If you’ve already added and verified such a domain, skip to Step 2.

Running the Azure AD Connect tool and following its prompts makes these required configuration changes automatically. The steps outlined here can be run manually if required.

Steps

  1. Add a federated domain to your account: Authenticate to Office 365 using the Connect-MsolService PowerShell cmdlet and enter the same credentials used when authenticating to the Microsoft Online Services portal.

    Choose from:

    • Add a new domain using Azure AD or Office 365 Admin Portals. Learn more in the following sections of the Microsoft documentation:

    • Add a new domain manually with PowerShell.

      You can load this and the other cmdlets described here by launching PowerShell from the Microsoft Azure Active Directory Module for Windows PowerShell desktop and Start menu shortcuts.

      1. To add a new domain, run the New-MsolDomain -Name <name> -Authentication Managed command.

      2. To get DNS verification records for the new domain, run the Get-MsolDomainVerificationDns -DomainName <name> command.

      3. To prove that you control the domain, use the output of the Get-MsolDomainVerificationDNS command to create a .txt record on the DNS server of the domain used in the previous step.

        This server must be accessible over the Internet so that Microsoft servers can resolve and access them.

        The DNS record name should match the Domain Name and the DNS record value should be MS=<ms portion of the Label>.

        The following is an example from the Get-MsolDomainVerificationDNS command.

        Screen capture showing the PowerShell prompt with the results of the Get-MsolDomainVerificationDNS command

        Creating a DNS record value can vary between different DNS host providers. Learn more about how to Add a domain to Microsoft 365 in the Microsoft documentation.
        Example Values for Creating a Text Record
        Record Type Alias or hostname Destination or Points to Address TTL

        .txt

        @ or jkdoctest.com

        MS=ms60016396

        1 Hour

        MX

        @ or jkdoctest.com

        Ms60016396.msv1.invalid.outlook.com

        1 Hour

      4. To prove your control of the domain, run the Confirm-MsolDomain -DomainName <name> command.

  2. Complete the steps in Enabling federated authentication.

  3. Complete the steps in Configuring multiple domains.

  4. To verify that the domain settings are up to date and in effect, run the Get-MsolDomainFederationSettings -DomainName <name> command.

  5. To change domain settings after the domain is created and verified, run the Set-MsolDomainFederationSettings -DomainName command with extra arguments for the settings that you want to change.

Enabling federated authentication

The default authentication type in the Azure AD or Office 365 domain is managed, which means that access is provided only for Azure AD cloud user identities. To allow usage of the on-prem user accounts, change the authentication type to federated.

About this task

Running the Azure AD Connect tool and following its prompts makes these required configuration changes automatically. The steps outlined here can be run manually if required.

You can complete the configuration manually using the Set-MsolDomainAuthentication PowerShell cmdlet. When you run it, you must provide the URLs for PingFederate, the public portion of its signing certificate, and some other inputs.

The IssuerURI parameter should be unique so that Office 365 can identify your identity provider (IdP).

Steps

  1. Export the signing certificate from PingFederate:

    1. Go to Server Configuration > Signing & Decryption Keys & Certificates.

    2. Export the applicable signing certificate to the local file system, such as C:\temp\pf-signing.crt.

    3. When prompted, select Certificate Only.

  2. Use PowerShell to remove unnecessary lines from the certificate file and configure federation for your Azure AD domain.

    Example:

    $certFile = "C:\temp\pf-signing.crt"
$cert = [IO.File]::ReadAllText($certFile)
$cert = $cert.replace("-----BEGIN CERTIFICATE-----","")
$cert = $cert.replace("-----END CERTIFICATE-----","")
$cert = $cert.replace("`r","")
$cert = $cert.replace("`n","")
$domainName = "<Federated Domain Name>"
$hostName = "<Hostname>.$domainName"
$port = 9031
${pingfed} = "https://${hostName}:$port"
$brandName = "<Federated Domain Alias>"
$issuer = "<WS-Federation Realm or Virtual Server ID>"
$spId = "urn:federation:MicrosoftOnline"
$activeLogOn = "$pingfederate/idp/sts.wst"
$logOff = "$pingfederate/idp/prp.wsf"
$metaData = "$pingfederate/pf/sts_mex.ping?PartnerSpId=$spId"
$passiveLogOnPF="$pingfederate/idp/prp.wsf"
Set-MsolDomainAuthentication -Authentication Federated -DomainName
"$domainName" -ActiveLogOnUri  "$activeLogOn" -FederationBrandName
"$brandName" -IssuerUri "$issuer"  -LogOffUri "$logOff" -MetadataExchangeUri
"$metaData" -PassiveLogOnUri  "$passiveLogOnPF" -SigningCertificate "$cert"

    Learn more about the Set-MsolDomainAuthentication command in Set-MsolDomainAuthentication in the Microsoft documentation.

  3. To verify that the domain settings are up-to-date and in effect, run the Get-MsolDomainFederationSettings -DomainName <name> command.

    If you have multiple subdomain accounts in Office 365, you can connect to them in one service provider (SP) connection using multiple virtual server IDs in PingFederate 7.2 or later.

Configuring multiple domains

About this task

A single PingFederate server connection can support multiple Azure AD and Office 365 domains. This functionality relies on using Virtual Server ID (VSID) feature.

The VSID value overrides the WS-Federation Realm value configured in the server settings. It should be created for each domain you’re going to federate with and added to the connection configuration.

The same VSID value should be used for the IssuerURI parameter while configuring federation settings on the Azure AD side. The encoded VSID value should be added to all endpoint URIs, so the incoming requests can be processed correctly by the PingFederate server.

If you use the Azure AD Connect wizard to federate with PingFederate server, it generates the VSID value for each specified domain. This parameter is listed in the configuration file, which should be exported from the wizard to obtain required PingFederate server settings. The Azure AD Connect wizard adds the encoded VSID value to all corresponding URIs while completing the Azure AD side configuration.

In a situation where you decide to use manual configuration, if both the engineering and marketing departments of contoso.com have their own departmental subdomains, engineering.contoso.com and marketing.contoso.com, they are both registered in Azure AD or Office 365 under the parent domain, contoso.com. As an example, their IssuerUri values are Engineering and Marketing, respectively.

When you run the Set-MsolDomainAuthentication PowerShell command, you must include the base64-encoded value of the VSID presenting that subdomain in the paths for the ActiveLogOnUri, LogoffUri, PassiveLogOnUri, and MetadataExchangeUri parameters.

Steps

  1. Construct a JSON object containing a key-value pair of the virtual server ID in the format of {"vsid":"<VirtualServerIdValue>"}.

    Example:

    {"vsid":"Engineering"}

  2. Base64url-encode the JSON object.

    Example:

    eyJ2c2lkIjoiRW5naW5lZXJpbmcifQ

  3. Insert the base64url-encoded value between /idp or /pf and the rest of the respective endpoint for ActiveLogOnUri, LogoffUri, PassiveLogOnUri, and MetadataExchangeUri.

    Example:

    $activeLogOn = “$pingfederate/idp/eyJ2c2lkIjoiRW5naW5lZXJpbmcifQ/sts.wst”
$logOff = “$pingfederate/idp/eyJ2c2lkIjoiRW5naW5lZXJpbmcifQ/prp.wsf”
$metaData = "$pingfederate/pf/eyJ2c2lkIjoiRW5naW5lZXJpbmcifQ/sts_mex.ping?PartnerSpId=$spId"
$passiveLogOnPF = “$pingfederate/idp/eyJ2c2lkIjoiRW5naW5lZXJpbmcifQ/prp.wsf”

  4. Repeat step 1-3 for each subdomain.

    Learn more about base64url in RFC 4648 on the Internet Engineering Task Force (IETF) website.