Configuring the Okta Template WS Federation Application

Okta provides a WS-Federation template appAn abbreviation of application. Essentially, it is a web-based site used to perform any number of specific tasks, and requires authentication from end users by signing in. through which you can create WS-Fed enabled apps on demand.

When using this template application, Okta acts as the IDPAn acronym for Identity Provider. It is a service that manages end user accounts analogous to user directories such as LDAP and Active Directory, and can send SAML responses to SPs to authenticate end users. Within this scenario, the IdP is Okta. (identity provider) and the target application will be the SPAn acronym for service provider. Generally, an SP is a company, usually providing organizations with communications, storage, processing, and a host of other services. Within Okta, it is any website that accepts SAML responses as a way of signing in users, and has the ability to redirect a user to an IdP (e.g., Okta) to begin the authentication process. (service provider).

For WS-Fed, Okta (acting as the IDP) supports SP-initiated authentication. The following is the authentication flow:

  1. Go to the target SP first or click on the chicklet in Okta. You should not have a session established with the SP.
  2. The SP redirects the user to the configured Login URL (Okta's generated app instance URL) sending a passive request.
  3. Okta is sent a passive request (assuming you have an existing Okta session).
  4. Okta sends a response to the configured SP.
  5. The SP receives the response and verifies that the claims are correct. A session is established on the SP side.
  6. You are authenticated.

There is additional configuration required on the target app (SP) with which you are configuring WS-Fed. Okta provides this information in our WS-Fed app instructions (accessible from the Sign on tab in the WS-Fed app screen). The instructions contain the following: realm, issuer, passive URL (normally only needed in the SP-initiated flow mentioned above). This is app dependent. We recommend you check with your SP vendor to see if turning on WS-Fed is an all-or-nothing feature.

Realm Names

The realm name must be unique for the IdP. Not all relying parties support the usage of a generated, unique endpoint on a per-party basis. The WS-Federation Template App supports two realm modes.

In both configurations, the issuer of the SAMLAn acronym for Security Assertion Markup Language, SAML is an XML-based standard for exchanging authentication and authorization data between an identity provider (IdP) and a service provider (SP). The SAML standard addresses issues unique to the single sign-on (SSO) solution, and defines three roles: the end user, the IDP, and the SP. Assertion is always the app instance key; for example[key]. The audience is always the configured Audience Restriction value. Okta recommends using the same value as the realm name, but a different value can be used, if necessary.

Configuring Template WS-Fed

The first thing you'll need to do is to add the Template WS-Fed app to your orgThe Okta container that represents a real-world organization.. You must add the private app first as a super user.

  1. Login to the Okta adminAn abbreviation of administrator. This is the individual(s) who have access to the Okta Administrator Dashboard. They control the provisioning and deprovisioning of end users, the assigning of apps, the resetting of passwords, and the overall end user experience. Only administrators have the Administration button on the upper right side of the My Applications page. app, go to Applications, click on the Add Application button and enter Template WS-Fed in the Search box.
  2. Complete the following fields in the Template WS-Fed app. Refer to your target application's (SP) documentation for more information on what you need to enter in these fields.
    • Application Label: Give your app a label that will display on your usersIn Okta literature, we generally refer to "users" as the people who serve as Okta administrators. When we refer to "end users" we are generally referring to the people who the administrators serve. That is, those who use Okta chiclets to access their apps, but have no administrative control.' home pages.
    • Web Application URL: Launch URL for the web application; for example,
    • Realm: One of several domains that are configured to share resources securely. The realm is the uniform resource identifier (URI) of the application. It is the identity that's sent to the Okta IdP when signing in. Okta generates the realm for you if you don't specify one, as indicated in the setup instructions. See Realm Names above for more information.
    • ReplyTo URL: This is the WS-Fed SP endpoint (i.e., where your users log in). For example,
    • AllowReplyToOverride: This enables a web application to override the ReplyTo URL with a reply parameter.
    • Name ID format: The value you choose will depend on the application. This is the username format that you are sending in the WS-Fed response. Consult the SP documentation to get this information.
    • Audience Restriction: This is the entity ID of the SP. It will be provided by the SP and must match exactly. Consult the SP documentation to get this information.
    • Assertion Authentication Context: This tells you the type of authentication restriction. This typically must be set to Password Protected Transport. Consult the SP documentation to get this information.
    • Attribute Statements (Optional): You can federate user attributes such as Okta profile fields, LDAP, Active Directory, and Workday values. The SP will use the federated WS-Fed attribute values accordingly. See Mapping Active Directory, LDAP, and Workday Values in a Template SAML 2.0 or WS Fed Application for more information.
    • Group Name (Optional): Enter a name for this attribute that will be included in the WS-Fed response attribute statement. Then enter the groupsGroups allow you to organize your end users and the apps they can access. Assigning apps to large sets of end users is made easier with groups. (using expressions) in the group filter field to specify which groups are included with this attribute. Any users that belong to the group you've filtered will be included in the WS-Fed response attribute statement.
    • Group Attribute Value: Specifies the WS-Fed assertion attribute value for filtered groups. This attribute is only applied to Active Directory groups.Choices are WindowsDomainQualifiedName, samAccountName, and dn.
    • Group filter (Optional): Specify which User Groups you want included with the attribute you configured in the Group Name field. Enter a regular expression that will be used to filter the groups. If the matching User Group has a corresponding AD group, then the attribute statement includes the value of the attribute specified by Group Attribute Value. If the matching User Group does not contain a corresponding AD group then the group name is used in the attribute statement.
    • User Attribute Statements: Specifies additional username attribute statements to include in the WS-Fed assertion. This simplifies integration with .NET apps that ignore subject statements. Your choices include username, UPN, username and UPN, and none.
    • Application Visibility (Optional): You can choose to hide the application from your users' home pages.

Configuring WS-Fed in the Target Application (SP)

In order for WS-Fed to work, you must perform some additional steps in the target application (SP).

Note: We recommend that you call the vendor for your SP and determine if enabling SAML is an all or nothing option. Okta provides all of the necessary configuration information you need to make in the target SP.

To access this information, do the following:

  1. Click on the instance of the template app you added.
  2. Click on the Sign-on tab and click on the View Setup Instructions link.

  3. In the instructions screen, scroll to the Configuration Data section where you can get all the necessary SP endpoint configuration information.


Assign a user to the app and verify that they are able to authenticate successfully.