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 will be the SP (service provider).
For WS-Fed, Okta (acting as the IDP) supports SP-initiated authentication. The following is the authentication flow:
- Go to the target SP first or click on the app in Okta. You should not have a session established with the SP.
- The SP redirects the user to the configured Login URL (Okta's generated app instance URL) sending a passive request.
- Okta is sent a passive request (assuming you have an existing Okta session).
- Okta sends a response to the configured SP.
- The SP receives the response and verifies that the claims are correct. A session is established on the SP side.
- 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.
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 target app instance is identified by the
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, but it is not 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 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 org. You must add the private app first as a super user.
- Login to the Okta admin app, go to Applications, click on the Add Application button and enter Template WS-Fed in the Search box.
- 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 users' 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, 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 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 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.
- Username 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.
- 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.
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:
- Click on the instance of the template app you added.
- Click on the Sign-on tab and click on the View Setup Instructions link.
- 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.