Configure the Okta Template WS Federation Application

Okta provides a WS-Federation template app through which you can create WS-Fed enabled apps on demand.

When using this template application, Okta acts as the IdP (Identity Provider) and the target application is the SP (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 the app in Okta. You shouldn't 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 that 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. This establishes a session on the SP side.
  6. You're authenticated.

There's more configuration required on the target app (SP) that you're using to configure WS-Fed. Okta provides this information in our WS-Fed app instructions (accessible from the Sign on tab in the WS-Fed app page). The instructions contain the following: realm, issuer, passive URL (normally only needed in the SP-initiated flow mentioned previously). The configuration is app-dependent. Okta recommends that 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.

  • Shared endpoint with an Okta-generated realm name

    If you leave the realm name empty, Okta generates a realm name with the app's external key; for example https://[orgname].okta.com/app/template_wsfed/sso/wsfed/passive. The relying party uses a common endpoint for requests, and the wtrealm=urn:okta:app:[key] query parameter identifies the target app instance.

  • App endpoint with a customer-defined realm name

    If you specify a realm name, Okta generates an app-specific endpoint; for example, https://[orgname].okta.com/apt/template_wsfed/[key]/sso/wsfed/. Realm names can be reused, since the namespace is the app and not global. The realm name is validated for matching with the configured value and isn't used for anything else.

In both configurations, the issuer of the SAML Assertion is always the app instance key; for example http://www.okta.com/[key]. The audience is always the configured Audience Restriction value. Okta recommends using the same value as the realm name, but you can use a different value, if necessary.

Add and configure Template WS-Fed

The first thing that you need to do is to add the Template WS-Fed app to your org. You must add the private app first as a super user.

  1. In the Admin Console, go to Applications, click Browse App Catalog, and then 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 to display on your users' home pages.
    • Web Application URL: The launch URL for the web application; for example, http://example.com.
    • Realm: One of several domains that are configured to share resources securely. The realm is the uniform resource identifier (URI) of the application. It's 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.
    • ReplyTo URL: This is the WS-Fed SP endpoint (that is, where your users log in). For example, http://test.acme.com/example-post-sign/.
    • AllowReplyToOverride: This enables a web application to override the ReplyTo URL with a reply parameter.
    • Name ID format: The value you choose depends on the application. This is the username format that you send in the WS-Fed response. Consult the SP documentation for this information.
    • Audience Restriction: This is the entity ID of the SP. It's 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 uses 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 to include in the WS-Fed response attribute statement. Then enter the 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 are 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 to use 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 doesn't contain a corresponding AD group, then the group name is used in the attribute statement.
    • Username Attribute Statements: Specifies other 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.
    • Custom Attribute Statements: Defines custom SAML attribute statements.
    • Signature Algorithm: Select either SHA1 or SHA256.
    • Digest Algorithm: Select either SHA1 or SHA256.
    • Application Visibility (Optional): You can choose to hide the application icon from your users' home pages.

Configure WS-Fed in the target application (SP)

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

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

To access this information, do the following:

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

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

Test the app

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

Related topic

Configure the Okta Template App and Okta Plugin Template App