This site contains the documentation that is relevant to older WSO2 product versions and offerings.
For the latest WSO2 documentation, visit https://wso2.com/documentation/.

Logging in to Microsoft Exchange using Identity Server

Owned by Former user (Deleted)
Last updated: May 27, 2019
6 min read

WSO2 Identity Server (WSO2 IS) is capable of authenticating the users who want to log in to Microsoft Exchange (MS Exchange). This sectino explains how to configure MS Exchange and WSO2 Identity Server so that Active Directory (AD) users can log in to Outlook Web Access/Exchange Administration Center (OWA/EAC). 

Overview

Let's get familiar with the related concepts first! 

EntityDescriptionExample
End User

This entity gets authenticated via the Authorization Server in order to log in to the Client.

AD users

Client/ Service Provider

This entity requires the End Users to be authenticated and obtain Claims by presenting an ID_token to an Authorization Server.MS Exchange

Authorization Server/ Identity Provider

This entity authenticates the End User and provides Claims to the Client.WSO2 Identity Server
ClaimThis is the information about the End User.

Name, address, and birth date

ID_TokenThis is a JSON Web Token (JWT) that Clients present to the Authorization Server in order to obtain the Claims.

In this scenario,

  • WSO2 Identity Server acts as a PassiveSTS-based Identity Provider
  • MS Exchange/OWA/EACT acts as the Service Provider
  • Authentication takes place based on the AD-specific user claims, ActiveDirectoryUPN, and ObjectGUID

Configuring Microsoft Exchange

Follow the steps below to configure MS Exchange.

  1. Download and install Microsft Exchange server. For instructions, see Install Exchange Mailbox servers using the Setup wizard guide. 

    This document is based on Microsoft Exchange server 2016.

Adding the WSO2 Identity Server Public Certificate to the Windows Instance

Follow the steps below to import the WSO2 Identity Server public certificate into Windows as a “Trusted Root Certification Authority ”.

  1. Execute the mmc.exe command on the command prompt. Note that a new console window opens.

  2. Click File > Add/Remove Snap-in.... Note that a pop-up window opens that allows adding a new snap-in.

  3. Select Certificates and click Add. Note that another pop-up window opens.

  4. Select Computer Account and click Next. 

  5. Select Local Computer and click Finish.

  6. Click OK to add the new snap-in.

  7. Expand Certificates, i.e., the new snap-in.

  8. Right-click on Trusted Root Certification Authorities and select All Tasks > Import. Note that a wizard opens.

  9. Follow the wizard to add the new Trusted Root CA cert. Once the import is successful, the Trusted Root Certification Authority appears on the list.  


Configure OWA and EAC Service Providers

Follow the steps below to configure OWA and EAC.

When configuring OWA and EAC, you need to specify the thumbprint of the certificate, which will use for WS-Federation with WSO2 Identity Server. We will use the certificate added as a “Trusted Root Certification Authority ” in the previous step. With the following command, you can find out the ‘thumbprint’ of this certificate. 

  1. Open “Exchange Management Shell” with searching in the start menu.

  2. Execute the following command to get the list of available certificates and their thumb prints. 

    [PS] > Set-Location Cert:\LocalMachine\Root; Get-ChildItem | Sort-Object Subject

    Note that a list of Trusted Root CA certificates appear.

  3. Locate the required certificate from the list of entries that will be similar to the following. 

    6BF8E136EB36D4A56EA05C7AE4B9A45B63BF975D  CN=localhost, O=WSO2, L=Mountain View, S=CA, C=US

    The first portion of the entry is the certificate thumbprint that you have to use when configuring the trust between the organizations.

  4. To configure OWA and EAC organizations, execute the following command on the Exchange Management Shell. 

    Format:

    [PS] > Set-OrganizationConfig -AdfsIssuer <PASSIVESTS_URL_OF_WSO2_IS> -AdfsAudienceUris
"<OWA_URL>","<EAC_URL>" -AdfsSignCertificateThumbprint "<CERTIFICATE_THUMB_PRINT>"

    Example: 

    [PS] > Set-OrganizationConfig -AdfsIssuer https://192.168.53.186:9443/passivests -AdfsAudienceUris
"https://digipolisprod-7.wso2.test/owa/","https://digipolisprod-7.wso2.test/ecp/" -AdfsSignCertificateThumbprint "6BF8E
136EB36D4A56EA05C7AE4B9A45B63BF975D"

  5. To disable all other authentication types except for the ADFS authentication in both ECP and OWA Virtual Directories, execute the following commands in the Exchange Management Shell.  

    For ECP: 

    [PS] >Get-EcpVirtualDirectory | Set-EcpVirtualDirectory -AdfsAuthentication $true -BasicAuthentication $false -DigestAuthentication $false -FormsAuthentication $false -WindowsAuthentication $false

    For OWA:  

    [PS] >Get-OwaVirtualDirectory | Set-OwaVirtualDirectory -AdfsAuthentication $true -BasicAuthentication $false -DigestAuthentication $false -FormsAuthentication $false -OAuthAuthentication $false -WindowsAuthentication $false

Configuring WSO2 Identity Server

  1. To import the certificate of the above-created Active Directory user store to the WSO2 Identity Server truststore (client-truststore.jks), execute the following command. 

    The client-truststore.jks resides in the <IS_HOME>/repository/resource/security directory.

    keytool -import -trustcacerts -alias adcacert -file /cert_file_path/ADcert.cer -keystore <IS_HOME>/repository/resource/security/client-truststore.jks -storepass wso2carbon

  2. To import the MS Exchange server certificate to the WSO2 Identity Server truststore, execute the following command. 

    keytool -import -trustcacerts -alias msExchange -file /cert_file_path/msExchange.cer -keystore IS_HOME/repository/resource/security/client-truststore.jks -storepass wso2carbon

  3. Configure the above-created Active Directory user store as the primary user store in WSO2 Identity Server. For detailed instructions, see Configuring an Active Directory User Store. 

    Make sure you do not start WSO2 Identity Server until the remaining steps are executed.

  4. Configure WSO2 Identity Server to authenticate users with email address as the user name. For detailed instructions, see Using Email Address as the Username. This changes certain properties specified in the previous step.

  5. Open the user-mgt.xml file in the <IS_HOME>/repository/conf directory and change the objectClass value of the UserNameSearchFilter and UserNameListFilter properties according to the user type in the Active Directory.

  6. Start WSO2 Identity Server using either of the following commands. 

  7. Sign in to the WSO2 Identity Server Management Console with one of the following URLs using credentials of the admin user that is in the AD. This user is defined in the <IS_HOME>/repository/conf/user-mgt.xml file. 

    For HTTP  --> http://<HTTP_HOST>:9776/carbon
For HTTPS --> https://<HTTPS_HOST>:9443/carbon

  8. On the Main menu, click Identity Providers > Resident. 

  9. Expand Inbound Authentication Configuration and WS-Federation (Passive) Configuration. 

  10. Verify the value of the PassiveSTS URL against AdfsIssuer that you specified before.

  11. On the Main menu, click Claims >  Add. 

  12. Set objectGUID and ActiveDirectoryUPN as claims as given below. For detailed instructions, see Adding Claim Mapping. 

  13. On the Main menu, click Claims > List.

  14. Click http://wso2.org/claims  claim dialect.

  15. Click Edit of the claims below and deselect the Supported by Default check box.

    1. Country - http://wso2.org/claims/country

    2. Organization - http://wso2.org/claims/organization

    3. IM - http://wso2.org/claims/im

    These attributes are not supported by Active Directory by default. If these attributes are ticked as Supported by Default, they will be shown in the default user profile causing an error once when updating the user profile.

  16. On the Main menu, click Service Providers > Add.
  17. To create a service provider, enter OWA as the name and click Register.

  18. Expand Inbound Authentication Configuration and WS-Federation(Passive) Configuration and enter the following details. 

    FieldDescriptionSample Value
    Passive STS Realm

    Macro lookup error: excerpt "PassiveSTSRealm" was not found on page "Configuring WS-Federation Single Sign-On" (with ID 38176257) in space "IS570".

    If you're experiencing issues please see our Troubleshooting Guide.

    		https://digipolisprod-7.wso2.test/owa/
    Passive STS WReply URL

    Macro lookup error: excerpt "PassiveSTSWReplyURL" was not found on page "Configuring WS-Federation Single Sign-On" (with ID 38176257) in space "IS570".

    If you're experiencing issues please see our Troubleshooting Guide.

    		https://digipolisprod-7.wso2.test/owa/

  19. Expand Claim Configuration.

    1. Configure the attributes that are required by OWA as given below. 

      Service Provider ClaimLocal Claim (WSO2 Identity Server)Request Claim

      http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn

      http://wso2.org/claims/userPrincipalName

      Ticked (True)

      http://schemas.microsoft.com/LiveID/Federation/2008/05/ImmutableID

      http://wso2.org/claims/objectGUID

      Ticked (True)

    2. Set Subject Claim URI to the Immutable ID claim.

  20. Similarly, add a new Service Provider named EAC and configure the following.

    1. Passive STS Realm - https://digipolisprod-7.wso2.test/ecp/

    2. Passive STS WReply URL -   https://digipolisprod-7.wso2.test/ecp/

    3. Configure the attributes that are required by EAC as given below. 

      Service Provider ClaimLocal Claim (WSO2 Identity Server)Request Claim

      http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn

      http://wso2.org/claims/userPrincipalName

      Ticked (True)

      http://schemas.microsoft.com/LiveID/Federation/2008/05/ImmutableID

      http://wso2.org/claims/objectGUID

      Ticked (True)

    4. Set the Subject Claim URI to the Immutable ID claim.

  21. NOTE: ObjectGUID is a binary attribute. Hence, you must add the following user store property to the <IS_HOME>/repository/conf/user-mgt.xml file under the org.wso2.carbon.user.core.ldap.ActiveDirectoryUserStoreManager user store. (You have to restart WSO2 Identity Server after this configuration change.) 

    <Property name="transformObjectGUIDToUUID">false</Property>
<Property name="java.naming.ldap.attributes.binary">objectGUID</Property>

    In order to verify the above configurations, sign in with a user in AD and check whether the user meets the following items.

    • User is in the Active Directory

    • User has a role in WSO2 Identity Server, which has login permission. (For trying out, you can add login permission to the ‘Internal/everyone’ role)


    • A mailbox on EAC is configured.

Testing the SSO Flow

  1. Access the following URLs that will redirect you to the WSO2 Identity Server login page.
    • https://<MS_EXCHANGE_HOST>/owa/
    • https://<MS_EXCHANGE_HOST>/ecp/

  2. Sign in with the AD user credentials.

    User name should be in email format.

    Note that you get authenticated from WSO2 Identity Server and get redirected to the related application, i.e., OWA or EAC.