How To: Configure Okta as an Identity Provider in K2 Five
OKTA APPLICATIONS & K2
To configure Okta as an identity provider in K2, you need to configure an Application in Okta for the K2 web application that includes the web application Realm. Each Okta Application has a unique Issuer and Passive Endpoint. In K2, there are three applications (Designer, Runtime and ViewFlow), each with a unique Realm. If you configure a separate Okta Application for each K2 application, since the Passive Endpoint is unique, you will need to create three issuers in K2 that all map to the same label.
This is clearly not desirable as you would need to expose all three issuers for login and select the appropriate issuer when logging in, depending on the K2 application being used.
Even if you expose only one of the issuers for login, for example Runtime, when you attempt to use this issuer to login into Designer (assuming you have not already authenticated via Runtime), the wtrealm parameter sent in the request will not match the realm configured for the Runtime application in Okta:
and Okta will throw the following exception:
To get around this, you can configure a single Application in Okta for Smartforms and update the configuration in K2 to use the Realm configured in Okta.
CONFIGURE AN OKTA APPLICATION FOR K2
Login to your Okta environment and navigate to the Admin site. From the Applications page, click the Add Application button:
Search for the WS-Fed template and click the Add button:
Complete the General Settings section of the template using the appropriate URL’s for your
environment. The Realm is case sensitive and must be an exact match of the Realm value that will be used in K2. Make sure to check the Allow ReplyTo Override checkbox:
Use the defaults for the rest of the general settings. Click the Done button at the bottom of the General Settings page to create the Application in Okta:
The Application page will be displayed with its own menu. Click on the Sign On tab:
Click the ‘View Setup Instructions’ button to get the metadata needed to configure Okta as an issuer in K2:
UPDATE THE REALM IN WEB.CONFIG FILES
Edit the Runtime, Designer and ViewFlow web.config files on the K2 server and set the realm to match the value of the Realm configured in the Okta application:
Again, this must be an exact match and is case sensitive.
CONFIGURE THE OKTA ISSUER
Navigate to the Authentication > Claims section of the Management site in K2 and add a new issuer for Okta. All metadata needed to configure the issuer is available in the Setup Instructions for the Okta application as seen above.
CONFIGURE THE CLAIM TYPE MAPPING
Create a new Claim Type Mapping for the Okta issuer and map it to the OKTA security label:
In this example, the OKTA security label has already been configured in K2 and uses the K2 LDAP User Manager, where the identity of the user in K2 is assumed to be userPrincipalName.
Notice that the Identity Claim Type is set to the nameidentifier claim returned in the claims token, which contains the email address of the user as the Claim Value. This matches the identity of the users cached against the OKTA security label in K2 and will therefore work for purposes of testing and validating the configuration. In a real-world scenario, you would likely integrate Okta with AD or an LDAP directory.
To determine the proper Identity Provider and Identity claim mapping values, leave them blank and save the Claim Type Mapping. Complete the rest of the configuration. When you attempt to login to K2 the first time using the Okta issuer, you will get an error indicating there is claims configuration issue. The error, along with the ArraryOfClaimsCollectionData xml that represents the decrypted claims token, will be logged to the HostServer log file. Use this to determine how to configure the claim mappings:
CONFIGURE THE REALM & AUDIENCES
Add a new Realm and link it to the Okta STS and K2 Windows STS:
The URI must match the Realm configured in the Okta application and the web.config files. The Reply URI must be set to a value that the authorize.aspx page can be accessed on. As long as the Allow ReplyTo Override is enabled in the Okta application, you will be redirected back to the application where the authentication request originated.
For example, when attempting to access the Designer and you are redirected to Okta for authentication, the request will look something like this:
The authorize.aspx is accessed in the /Runtime site and the request is redirected back to the Designer after the user is authenticated.
When you create the new realm in K2, the audience will be added by default:
ADD USERS IN OKTA
For testing purposes, you can manually add users in Okta that map to users in your K2 environment, rather than syncing K2 with Okta to populate the K2 Identity cache. In this example, the Denallix core is being used and the identity of an Okta user is expected to userPrincipalName. From the Admin site navigate to Directory > People page and click the Add Person button. Set the Username to the UPN of a Denallix user:
After adding the users, navigate to back to the K2 SmartForms application Assignments tab and click the Assign > Assign to People button:
Assign your test account as a user in the K2 SmartForms application:
LOGIN INTO K2 USING OKTA
Login into K2 using the Okta STS issuer:
The user is authenticated against the OKTA security label: