Configuring an Office 365 Domain to Federate with Access Manager

Prerequisite

Ensure that the following requirements are met before configuring an Office 365 domain:

  • Sign up for an Office 365 account.

  • To single-sign on to any of the Office 365 applications, ensure that you download it from the Office 365 portal.

  • Create a federated domain in Office 365 and prove ownership of it. By doing this you add your company domain into the Office 365 domain. For more information, see Adding and Verifying a Domain for Office 365.

  • Ensure that the Windows 7 or Windows 8 workstations do not have the Active Directory Federation Service 2.0 snap-in installed.

  • Ensure that the Identity Server Base URL SSL certificate is issued by a well-known external certification authority (CA).

  • Install Microsoft Live Sign-in Module to help manage and establish a remote session with the Office 365 account that is created to manage the Office 365 domain.

  • Install Microsoft Azure Active Directory Module. To download, click Install the MSonline module.

Setting Up Office 365 Services

Office 365 is preconfigured to establish federation with an external service providers.

Perform the following steps to create a trusted service provider:

  1. Click Devices> Identity Servers > Edit.

  2. Click SAML 2.0 > New >Service Provider.

  3. Select Provider Type as Office 365. Ensure that Source is selected as the Metadata Text.

  4. Specify a name for the Office 365 domain. The XML metadata is automatically populated in the Text field. Click Next.

  5. Confirm the certificates and click Finish to save the changes.

Establishing Trust Between an Identity Provider and a Service Provider

You can configure Office 365 domains federations by using the Microsoft Online Services Module. You can use the Microsoft Online Services Module to run a series of cmdlets in the Windows PowerShell command-line interface to add or convert domains for single sign-on.

Each Active Directory domain that you want to federate by using Access Manager must either be added as a single sign-on domain or converted to be a single sign-on domain from a standard domain. Adding or converting a domain sets up a trust between Access Manager and Office 365.

Adding a Domain:

To add a domain to Office 365, perform the following steps:

  1. Log in to Office 365 as an administrator.

  2. On the Administrator page, click Management > Domains > Add a domain.

  3. Specify the domain name that you want to add.

  4. Click Next.

  5. Verify the domain name.

  6. Select appropriate services.

  7. Configure the DNS records on the domain registrar for other services.

    NOTE:Do not configure the new domain to the primary domain. Using the Set­MsolDomainAuthentication command to set the domain as a federated domain results in an error if the domain is the default domain.

Converting a standard domain to a federated domain:

  1. Open the Microsoft Online Services Module from the Start menu.

  2. Run $cred=Get-Credential. Enter your cloud service administrator account credentials.

  3. Run Connect-MsolService –Credential $cred.

    This cmdlet connects you to the cloud service. Creating a context that connects you to the cloud service is required before running any of the additional cmdlets installed by the tool.

    For example, if the name of the domain you are converting to a single sign-on domain is namtest.com, and the base URL of Identity Server is https://namtest.com:8443/nidp, execute the following commands at the Powershell prompt:

    1. $dom = "namtest.com"

    2. $url = "https://namtest.com:8443/nidp/saml2/sso"

    3. $ecpUrl = "https://namtest.com:8443/nidp/saml2/soap"

    4. $uri = "https://namtest.com:8443/nidp/saml2/metadata"

    5. $logouturl = "https://namtest.com:8443/nidp/jsp/o365Logout.jsp"

    6. $cert = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2("name and path of the certificate")

      NOTE:While executing this command, ensure that you specify the path to the certificate within the double quotes. For example: “C:\local\netiq-off365-sign.cer”

    7. $certData = [system.convert]::tobase64string($cert.rawdata)

  4. Use the following cmdlet to update the settings of the single sign-on domain:

    Set-MsolDomainAuthentication -FederationBrandName $dom -Authentication Federated -PassiveLogOnUri $url -SigningCertificate $certData -IssuerUri $uri -ActiveLogOnUri $ecpUrl -LogOffUri $logouturl -PreferredAuthenticationProtocol SAMLP

    NOTE:Ensure that there are no spaces after the hyphen if you are copy pasting the command.

Configuring Specific Attributes as ImmutableID

By default, Office 365 uses GUID as the ImmutableID. If you want to use any other attribute as the ImmutableID of the Office 365 user, configure and then add a property name/value pair.

  1. In Administration Console, go to Identity Server and select an Identity Server.

  2. Select SAML 2.0 and then select the service provider you created.

  3. Select Options and click New.

  4. Add a property name/value pair as follows:

    Property Name: SAML2_OFFICE365_NAMEID_ATTRIBUTE_NAME

    Property Value: title

The title you specify in Property Value must be base64 encoded and stored in the user store. This value must be used as ImmutableID while creating a user in Office 365.

Configuring Virtual Attributes as ImmutableID

Virtual attributes is helpful in the following scenarios:

  • Dynamically convert the clear-text value of an attribute into a base64 value.

  • Retrieve the attribute from an external datasource and use it as the ImmutableID

To use virtual attribute as ImmutableID, perform the following steps:

  1. Create a virtual attribute. See Managing a Virtual Attribute.

  2. Go to Devices > Identity Servers > Servers > Edit > SAML 2.0 > Service Provider > Options and add the following property for Office 365:

    • Property Name: SAML2_OFFICE365_NAMEID_ATTRIBUTE_NAME

    • Property Value: Specify the name of the virtual attribute

  3. Add the virtual attribute created in step 1 to the attribute set created for the SAML 2.0 service provider configuration for Office 365. This ensures that the name specified in SAML2_OFFICE365_NAMEID_ATTRIBUTE_NAME is mapped to the virtual attribute with that value. If the virtual attribute is not added to the attribute set, Access Manager considers the name as a normal LDAP attribute name.

Configuring Desktop Email Client to Access Office 365 Emails

You can configure your desktop email client to access Office 365 emails. The email clients must use a basic authentication and a supported exchange access method such as IMAP, POP, Active Sync, and MAPI.

The following are the list of email clients supported for this configuration:

  • Microsoft Outlook 2007

  • Microsoft Outlook 2010

  • Thunderbird 8 and 9

  • The iPhone (various iOS versions)

  • Windows Phone 7

NOTE:You can download the email clients from the download section of Office 365.

These steps are explained with an example where the federated domain name is namtest.com and the base URL is https://namtest.com:8443/nidp. Replace the domain name and base URL based on your system configuration.

  1. Open the Microsoft Online Services Module.

  2. Run the following command:

    $cred=Get-Credential

    Specify your cloud service administrator account credentials.

  3. Run the following command:

    Connect-MsolService –Credential $cred

    This cmdlet connects you to the cloud service.

  4. Execute the following command to check the existing domain federation settings:

    Get-MsolDomainFederationSettings -DomainName namtest.com

    Substitute namtest.com with your domain name before executing this command.

    In the output, look for the ActiveLogOnUri parameter.

    For Identity Server base URL https://namtest.com:8443/nidp, the value of the ActiveLogOnUri must be https://namtest.com:8443/nidp/saml2/soap. The ActiveLogOnUri is dependent on the base URL of Identity Server.

    If the value of ActiveLogOnUri in the command output is https://namtest.com:8443/nidp/saml2/soap, go to the next step without modifying the configuration.

    (Conditional) If the ActiveLogOnUri is not https://namtest.com:8443/nidp/saml2/soap, execute the following command. Substitute namtest.com and port 8443 with your domain name and port number respectively before executing the following command.

    Set-MsolDomainFederationSettings -DomainName namtest.com -ActiveLogOnUri "https://namtest.com:8443/nidp/saml2/soap" -preferredauthenticationprotocol SAMLP

  5. Create a new email account in your email client and enter your Office 365 email ID.

    NOTE:Configure Outlook related DNS settings before using email clients. You can configure these settings after adding the domain on the Office 365 port page.

  6. The system prompts for specifying the basic authentication. Specify Access Manager credentials.

    The email account is created after successful authentication.

    NOTE:While logging in to the new email account, enter Access Manager credentials.

Configuring Desktop Email Client to Access Office 365 Emails

You can configure your desktop email client to access Office 365 emails. The email clients must use a basic authentication and a supported exchange access method such as IMAP, POP, Active Sync, and MAPI.

The following are the list of email clients supported for this configuration:

  • Microsoft Outlook 2007

  • Microsoft Outlook 2010

  • Thunderbird 8 and 9

  • The iPhone (various iOS versions)

  • Windows Phone 7

NOTE:You can download the email clients from the download section of Office 365.

These steps are explained with an example where the federated domain name is namtest.com and the base URL is https://namtest.com:8443/nidp. Replace the domain name and base URL based on your system configuration.

  1. Open the Microsoft Online Services Module.

  2. Run the following command:

    $cred=Get-Credential

    Specify your cloud service administrator account credentials.

  3. Run the following command:

    Connect-MsolService –Credential $cred

    This cmdlet connects you to the cloud service.

  4. Execute the following command to check the existing domain federation settings:

    Get-MsolDomainFederationSettings -DomainName namtest.com

    Substitute namtest.com with your domain name before executing this command.

    In the output, look for the ActiveLogOnUri parameter.

    For the Identity Server base URL https://namtest.com:8443/nidp, the value of the ActiveLogOnUri must be https://namtest.com:8443/nidp/saml2/soap. The ActiveLogOnUri is dependent on the base URL of the Identity Server.

    If the value of ActiveLogOnUri in the command output is https://namtest.com:8443/nidp/saml2/soap, go to the next step without modifying the configuration.

    (Conditional) If the ActiveLogOnUri is not https://namtest.com:8443/nidp/saml2/soap, execute the following command. Substitute namtest.com and port 8443 with your domain name and port number respectively before executing the following command.

    Set-MsolDomainFederationSettings -DomainName namtest.com -ActiveLogOnUri "https://namtest.com:8443/nidp/saml2/soap" -preferredauthenticationprotocol SAMLP

  5. Create a new email account in your email client and enter your Office 365 email ID.

    NOTE:Configure Outlook related DNS settings before using email clients. You can configure these settings after adding the domain on the Office 365 port page.

  6. The system prompts for specifying the basic authentication. Specify Access Manager credentials.

    The email account is created after successful authentication.

    NOTE:While logging in to the new email account, enter Access Manager credentials.

Configuring Specific Attributes as ImmutableID

By default, Office 365 uses GUID as the ImmutableID. If you want to use any other attribute as the ImmutableID of the Office 365 user, configure and then add a property name/value pair.

  1. In Administration Console, go to Identity Server and select an Identity Server.

  2. Select SAML 2.0 and then select the service provider you created.

  3. Select Options and click New.

  4. Add a property name/value pair as follows:

    Property Name: SAML2_OFFICE365_NAMEID_ATTRIBUTE_NAME

    Property Value: title

The title you specify in the Property Value must be base64 encoded and stored in the user store. This value must be used as ImmutableID while creating a user in Office 365. If the value is in a clear text format, you need to use virtual attributes to convert it into a base64 format.

To use virtual attribute as ImmutableID, perform the following steps:

  1. Create a virtual attribute. See Managing a Virtual Attribute.

  2. Ensure that the final value of the virtual attribute is the base64 encoded value. You can achieve it in any of the following ways:

    • Configure a virtual attribute to retrieve a value stored in the clear text format from an attribute source (LDAP or database)

    • Transform the value into the base 64 encoded format by using the advanced JavaScript option

  3. Go to Devices > Identity Servers > Servers > Edit > SAML 2.0 > Service Provider > Options and add the following property for Office 365:

    • Property Name: SAML2_OFFICE365_NAMEID_ATTRIBUTE_NAME

    • Property Value: Specify the name of the virtual attribute

    This ensures that the NAMEID value is fetched based on the property name. Currently, the name is considered as a user attribute.

  4. Add the virtual attribute created in step 1 to the attribute set created for the SAML 2.0 service provider configuration for Office 365. This ensures that the name specified in SAML2_OFFICE365_NAMEID_ATTRIBUTE_NAME is mapped to the virtual attribute with that name. If the virtual attribute is not added to the attribute set, Access Manager considers the name as a normal LDAP attribute name.

Auto-Populating the Username on the Identity Server Login Page

When employees try to access an Office 365 application, they need to specify the username twice as follows:

  1. First, on the Microsoft login page

  2. Then, on the organization’s identity provider login page

Using Access Manager, you can enable auto-populating the email ID or username of a user on the corporate login page when the user accesses Office 365 applications. So that the user does not need to specify the username or email ID again.

For example, an employee named Steve Smith wants to access an Office 365 application. He performs the following steps:

  1. Launches a Microsoft’s page (www.office.com).

  2. Specifies his email ID (steve.smith@example.com).

    Steve is then redirected to the organization’s identity provider for authentication.

  3. Specifies the email ID again.

When auto-populating email ID or username is enabled, Steve does not need to perform Step 3.

Enabling Auto-Populating Email ID

  1. Click Devices > Identity Servers > Edit > General > Options.

  2. Click New and specify the following:

    Property Name: HTTP POPULATE LOGINNAME FROM SAML AUTH REQUEST

    Property Name: True

  3. Click OK > Apply.

  4. Update Identity Server.

    NOTE:Usernames are not populated if the Basic type authentication contracts are used.

Enabling Auto-Populating Username

To populate only the username instead of the entire email ID, perform the following steps. For example, populate steve.smith instead of steve.smith@example.com.

  1. Click Devices > Identity Servers > Edit > General > Options.

  2. Click New and specify the following:

    Property Name: HTTP POPULATE PARSED LOGINNAME FROM SAML AUTH REQUEST

    Property Name: True

  3. Click OK > Apply.

  4. Update Identity Server.

    NOTE:If both HTTP POPULATE LOGINNAME FROM SAML AUTH REQUEST and HTTP POPULATE PARSED LOGINNAME FROM SAML AUTH REQUEST properties are set to true, then the login page will display the entire email ID.

IMPORTANT:If you have customized any JSP file, add those changes to the login_latest.jsp file. For information about how to modify a file, see Modifying Configurations.

Verifying Single Sign-On Access

You need at least one user in Office 365 to verify that single sign-on is set up. If you have an existing user, ensure that the Immutable ID matches with the GUID of the Access Manager user.

Prerequisite:

You need at least one user in Office 365 to verify that single sign-on is set up. If you have an existing user, ensure that the Immutable ID matches with the GUID of the Access Manager user.

For instance, if your user store is eDirectory and you want to retrieve the GUID of an existing Access Manager user, execute the following command on the eDirectory server terminal:

ldapsearch -D cn=<context> -w <password> -b <search base> cn=<name of the user> GUID | grep GUID

Create an Office 365 user with this GUID as the Immutable ID using the following command in Powershell:

new-msolUser -userprincipalName "user1@domain name" -immutableID "GUID of user1" - lastname "lastname of user 1" -firstname user1 -DisplayName "user1 users" -BlockCredential $false -"LicenseAssignment testdomain:ENTERPRISEPACK" -usageLocation "two letter country code[example: US,IN,DE,BE,GB etc]" -Password "password of the user".

Verifying Single Sign-on:

To verify that single sign-on is set up correctly, perform the following procedure in a server that is not added to the domain:

  1. Go to Microsoft Online Services.

  2. Log in with your corporate credentials. (For example: user1@namtest.com)

    If single sign-on is enabled, the password field is dimmed. You will instead see the following message: You are now required to sign in at <your company>.

  3. Select the Sign in at your company link.

    If you are able to sign in without errors, single sign-on is set up successfully.