Configure the OktaIWA Web agent Universal Principal Name
This procedure is applicable only to enterprises with more than one domain, and requires IWA Web agent Version 1.8.1 or later.
In Windows Active Directory, the Universal Principal Name (UPN) is the name of a system user presented in an email format. You need to configure UPN transformation on your OktaIWA Web agents if your company has more than one domain and the domain that your users specify when they sign in to work is different from the domain that your Okta org is built upon. For example, your users sign in to work using username@abc.com, and your Okta org contains user names such as username@xyz.com.
In this case, the authenticated user names that your company sends to Okta will not match the user names in your Okta org. Instead of being signed in to their Okta dashboards automatically, your users will be prompted to enter their credentials. To fix this, add a rule in the web.config file to transform the authenticated user names that your company sends to your Okta org.
The match attribute specifies a regular expression that the IWA Web agent uses to check UPNs. If a UPN matches a UPN transformation rule, the IWA Web agent uses the expression specified by the replace attribute to compute a transformed UPN. For more information, see:
- match syntax: https://msdn.microsoft.com/en-us/library/az24scfc(v=vs.110).aspx
- replace syntax: https://msdn.microsoft.com/en-us/library/ewy2t5e0(v=vs.110).aspx
The IWA Web agent checks all rules consecutively in the order that they are specified in the configuration file and applies the first rule that matches the UPN. If no rule matches the UPN, the IWA Web agent sends the original UPN to Okta.
Administrators can use the /IWA/authenticated.aspx page to verify and debug the transformation rules.
- Navigate to C:\inetpub\wwwroot\IWA and open the file web.config.
- Insert the following rule inside the <upnTransformation> element (a child of the <oktaSSOConfigGroup> element). The rule will convert all user names from the domain abc.com to the domain xyz.com:
<upnTransformation> <rule match="(.+)@abc\.com" replace="${1}@xyz.com" /> </upnTransformation>
The same logic can be applied to other common use cases such as transforming company.local to company.com, or company.com to company.okta.com