Configuring Microsoft Entra integration with Liberty

You can validate the opendID Connect (OIDC)-based authentication during log in, log out, or time out. To use Microsoft Entra to manage user IDs and passwords, configure the Microsoft Entra as an identity provider.

Before you begin

Ensure that you have an Microsoft Entra account with the administrative access.

Procedure

Configure the following entries in the server.xml.

<openidConnectClient id="entra" 
clientId="yourclientid" clientSecret="yourclientsecret"  
discoveryEndpointUrl= 
"your_entra_discovery_url"
scope="openid email profile"
httpsRequired="true" signatureAlgorithm="RS256" 
authFilterRef="myAuthFilter"  
/>
<authFilter id="myAuthFilter">
<requestUrl id="bypass1" 
urlPattern="/restapi|/heartbeat|/MQConnVerifierServlet|/restapi_internal
|/servlets/scwcsoapservlet|/wms/error|/console/ibmid|/interop/
InteropHttpServlet" matchType="notContain" />

<requestUrl id="myURL" urlPattern="/sbc|/isccs|/wsc|/sfs|/sma|/smcfs|/isf"
matchType="contains" />
</authFilter>
<application context-root="smcfs" type="ear" id="smcfs" name="smcfs" location=" your location ">
            <application-bnd>
                <security-role name="All Role">
                    <special-subject type="ALL_AUTHENTICATED_USERS" />
                </security-role>
				<security-role name="ExcludeAuth">
                    <special-subject type="EVERYONE" />
                </security-role>
            </application-bnd>
</application>
<applicationMonitor dropinsEnabled="false" />

Replace the placeholder values yourclientId, yourclientsecret, and your_entra_discovery_url with the actual values.

The following is a sample server.xml with the given values configured.

Note: This is a sample file and no support is provided for the following configuration.

<server description="Default server">
    <!-- Enable features -->
    <featureManager>
        <feature>adminCenter-1.0</feature>
        <feature>jdbc-4.1</feature>
        <feature>jndi-1.0</feature>
        <feature>jsp-2.3</feature>
        <feature>servlet-3.1</feature>
        <feature>ssl-1.0</feature>
        <feature>appSecurity-2.0</feature>
        <feature>openidConnectClient-1.0</feature>
    </featureManager>

<httpDispatcher enableWelcomePage="false" />
<httpSession invalidateOnUnauthorizedSessionRequestException="true" />
<webContainer trustHostHeaderPort="true" extractHostHeaderPort="true"/>
<webContainer disableXPoweredBy="true"/>
<httpOptions removeServerHeader="true"/>

<httpEndpoint id="defaultHttpEndpoint" host="*" httpPort="9080" 
httpsPort="9443">
<httpOptions removeServerHeader="true" />
</httpEndpoint>

<sslDefault sslRef="defaultSSLSettings" />
    <ssl id="defaultSSLSettings" sslProtocol="TLSv1.2" 
keyStoreRef="defaultKeyStore" 
clientAuthenticationSupported="true" />
    <keyStore id="defaultKeyStore" location="##########" 
type="JKS" password="##########" />
 
<openidConnectClient id="entra" 
clientId="###############" clientSecret="###############"  
discoveryEndpointUrl= "#########"
scope="openid email profile"
httpsRequired="true" signatureAlgorithm="RS256" 
authFilterRef="myAuthFilter"  
/>
 <authFilter id="myAuthFilter">
<requestUrl id="bypass1" 
urlPattern="/restapi|/heartbeat|/MQConnVerifierServlet|/restapi_internal|/
servlets/scwcsoapservlet|/wms/error|/console/ibmid|/interop/
InteropHttpServlet" matchType="notContain" />
<requestUrl id="myURL" urlPattern="/sbc|/isccs|/wsc|/sfs|/sma|/smcfs|/isf"
matchType="contains" />
</authFilter>
<application context-root="smcfs" type="ear" id="smcfs" name="smcfs" 
location="################# ">
            <application-bnd>
                <security-role name="All Role">
                    <special-subject type="ALL_AUTHENTICATED_USERS" />
                </security-role>
                <security-role name="ExcludeAuth">
                    <special-subject type="EVERYONE" />
                </security-role>
            </application-bnd>
</application>
<applicationMonitor dropinsEnabled="false" />
</server>

Download the root CA certificate for Microsoft Entra from the Microsoft Entra discovery URL, and import the certificate to the keystore that is used by Liberty.
Add the ENABLE_IBMID_AUTHENTICATION=true property to the sandbox properties in the <Runtime>/properties/sandbox.cfg file.
Apply the sandbox configuration changes by running the following command:
```
<runtime>/bin/setupfiles.sh
```
Add the following properties to customer overrides:
Note: Based on the value set for the yfs.yfs.ibmid.provisioner.name property, the same value is applied to the remaining properties.. For example, if you define yfs.yfs.ibmid.provisioner.name=azure, the other properties use this value, which in this case is azure.
- yfs.yfs.ibmid.provisioner.name=entra
- yfs.yfs.ibmid.provisioner.entra.class=com.ibm.sterling.afc.auth.ibmid.IBMIDBlueIdImpl
- yfs.yfs.ibmid.provisioner.entra.uniqueClaim=sub
- yfs.yfs.ibmid.provisioner.entra.secondaryid=upn
- yfs.yfs.ibmid.provisioner.entra.logouturl= https://login.microsoftonline.com/common/oauth2/v2.0/logout
- yfs.yfs.oidc.logouturl.autoclose=false
  To ensure that the logout window does not automatically close, set the value to false. You are prompted to select the Microsoft Entra account to log out of the applications.
Note: An ID token claim named email is mandatory to link users. Ensure that your Active Directory configuration contains an email ID that is configured for the users that are intending to login to Sterling™ Order Management System Software. Also, ensure that you configure your OIDC provider to pass on email ID as an ID token claim. In case your claim is named anything other than "email", configure the yfs.yfs.ibmid.provisioner.entra.secondaryid=upn property.

For example, if you define your email claim as email_id, ensure that you update the following yfs.yfs.ibmid.provisioner.entra.secondaryid=email_id property in customer overrides.
Add the https://localhost:9443/oidcclient/redirect/entra URL to the list of sign-in redirect URLs in the Microsoft Entra configuration. This is a sample URL to use when you access the application from a local host. For the production environment, change it to https://<domain or ip:port>/oidcclient/redirect/entra to match your production domain or ip:port. For more information, see Microsoft Entra documentation.
Rebuild EAR and redeploy.
To verify whether the property is in effect, check the web.xml for smcfs.war. The file must contain security constraints entries, which are in relation to the security roles in the server.xml file.