Configuring OKTA integration with Liberty

Procedure

Configure following entries in the server.xml.

<openidConnectClient id="okta" 
clientId="yourclientid" clientSecret="yourclientsecret"  
discoveryEndpointUrl= 
"your_okta_discovery_url"
scope="openid"
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" />
Confidential, For INTERNAL use only
<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_okta_discovery_url with actual values.

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

Note: This is a sample file and no support will be 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="okta" 
clientId="###############" clientSecret="###############"  
discoveryEndpointUrl= "#########"
scope="openid"
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 cert from Okta and import it to the keystore used by Liberty.
Add the following property to sandbox properties in <Runtime>/properties/sandbox.cfg.
```
ENABLE_IBMID_AUTHENTICATION=true
```
Apply the sandbox configuration changes by running the following command:
```
<runtime>/bin/setupfiles.sh
```
Add the following properties to customer overrides:
```
yfs.yfs.ibmid.provisioner.name=okta
yfs.yfs.ibmid.provisioner.okta.logouturl=https://<your_okta_domain>/oauth2/default/v1/logout
yfs.yfs.ibmid.provisioner.okta.logoutHint.param=id_token_hint
yfs.yfs.ibmid.provisioner.okta.secondaryid=emailId
```
Replace the placeholder value your_okta_domain with actual value.
Note: By default Okta doesn't provide email ID claim in the ID token. You must update your Okta configuration in Okta administrative console for OIDC configuration to include email ID in ID token. The given properties assume that the email ID claim is named as emailId (case sensitive). Hence, you must ensure that in your Okta configuration is same or you can update the property yfs.yfs.ibmid.provisioner.okta.secondaryid.
For example, if you define it as email_id, ensure you update following property in customer overrides:yfs.yfs.ibmid.provisioner.okta.secondaryid=email_id
Add the URL https://localhost:9443/oidcclient/redirect/okta to the list of sign-in redirect URLs in Okta admin console for your OIDC configuration. This URL is an example when accessing the application from localhost. For production environment, you need to change it to https://<domain or ip:port>/oidcclient/redirect/okta to match your production domain or ip:port.
Rebuild EAR and redeploy.
To verify if the property is in effect, check the web.xml for smcfs.war. It should have the security constraints entries created which are in relation to the security Roles in server.xml.

After you have followed the configuration steps, redeployed the EAR, and restarted the server, you can access the application.

When you access the application over https, (for example, https://<host:port>/smcfs/console/login.jsp), you are redirected to Okta Login page. Once you successfully login to Okta, you are redirected to the application login page (first time login only) where you need to enter your OMS credentials. After the login, your Okta id is linked to the OMS user and your future login with Okta ID does not require OMS credentials.
Linking an OMS user with an Okta account

As an alternative to given login approach, you can provide an email ID for any new users you create in the IBM® Sterling Order Management System Software. This email ID is used to link the OMS user with an Okta account. Therefore, the email ID used when creating an OMS user and an Okta id must be the same. IBM Sterling Order Management System Software user creation can be done using either the Applications Manager UI or by calling the createUserHierarchy API.
When creating the user from UI, the email ID mentioned in contact person information panel, is used for the purpose of linking the OMS user to Okta ID. This only works when creating the user. Modifying the user's email to link to another Okta ID doesn't work. You must first delete the OMS user and then recreate it with new email id, if you wish to link an OMS user to a new Okta ID. The following text demonstrates sample input XML for the createUserHierarchy API:
```
<User Localecode="en_US_EST" Username="user1" Loginid="user1" Password="password">
<ContactPersonInfo EMailID="abc@xyz.com"/>
</User> 
```