Configure the Okta IWA Web agent Universal Principal Name

The Universal Principal Name (UPN) in Active Directory is a system user's name presented in an email format. You need to configure UPN transformation if your users sign in to a domain that differs from your Okta org.

For example, your users might sign in to work using username@abc.com, while your Okta org usernames have the format username@xyz.com. This means that the authenticated usernames that your company sends to Okta don't match the usernames in your Okta org. Instead of being automatically signed in to their Okta dashboards, your users are prompted to enter their credentials. You can fix this by adding a rule to the agent's web.config file that transforms an authenticated username to the username format for 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 about matching and replacing, see Regular Expression Language - Quick Reference and Substitutions in Regular Expressions.

The IWA Web agent checks the rules in the order that they're specified in the configuration file. It 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 /IWA/authenticated.aspx to verify and debug the transformation rules.

1. Edit the file C:\inetpub\wwwroot\IWA\web.config.

2. Insert the following as a child of the <oktaSSOConfigGroup> element. The rule takes any username that contains abc.com and converts it to use 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.