WS-Federation Applications
Configure a Federated Application to use Descope as a WS-Federation Identity Provider. Your relying party redirects users to Descope for authentication, Descope runs your configured flow, and returns a signed WS-Fed response to the reply URL. Use this when the application expects WS-Fed rather than OIDC or SAML — common with older Microsoft stacks and some enterprise portals.
Note
Configuring additional federated applications (beyond the default) is a Pro+ feature.
Creating a WS-Federation Application
Navigate to Federated Apps and click + Application. Choose a template from the Application Library or create a Generic WS-Federation Application. Provide an Application Name, and optionally an Application ID and Description.
You can also create and update WS-Fed apps with the Management SDKs or the Create SSO WS-Fed IDP application API.
Configuring a WS-Federation Application
Once created, configure the application from its settings page. You give your relying party Descope's IdP details, and you give Descope the relying party's realm and reply URL.
Application details
| Setting | Details |
|---|---|
| Application Name | Display name for the application (can be updated). |
| Application ID | Unique identifier (cannot be changed). Available in flows as the ssoAppID variable. |
| Application Description | Optional description of the application's purpose. |
Identity provider settings
Configure your relying party with Descope's details. Prefer the metadata URL when the RP supports it.
Metadata URL (recommended)
https://api.descope.com/v1/auth/wsfed/idp/metadata?app=<Application ID>If you're using a custom domain, replace api.descope.com with your custom domain.
The metadata response includes the entity ID, SSO URL, and signing certificate your RP needs to trust Descope as the IdP.
Manual configuration
If your RP does not fetch metadata, copy these values from the Identity Provider section in the Console:
- Entity ID
- SSO URL (passive / sign-in endpoint)
- Public Certificate
- IdP-Initiated URL (for IdP-started sign-in)
Relying party settings
Configure Descope with your RP's details:
| Setting | Details |
|---|---|
Realm (wtrealm) | The relying party identifier / realm your RP sends on sign-in requests. Must match what the RP is configured to use. |
Reply URL (wreply) | Where Descope posts the WS-Fed response after authentication (the RP's consumer / return URL). |
| Allowed reply callbacks | Optional additional reply URLs (exact or patterned) when the same app signs in across multiple environments. |
| Flow Hosting URL | Where users are redirected for authentication. Defaults to Descope Auth Hosting — see Auth Hosting. |
| Force Authentication | Forces flow execution even if the user is already signed in. |
| Logout Redirect URL | Where users land after logout from this application. |
| Error Redirect URL | Hosted page shown when a timeout or misconfiguration occurs during WS-Fed login. |
Attribute and group mapping
Map Descope user attributes and roles into the claims your RP expects in the WS-Fed response, the same way you would for SAML:
- User attribute mapping — map Descope fields (email, name, phone, custom attributes) to the claim names the RP requires.
- Group mapping — map Descope roles to the group claim names the RP expects.
Sign-in flows
Relying-party-initiated (passive)
The RP redirects the user to Descope's passive SSO endpoint with standard WS-Fed parameters (wa, wtrealm, wreply, and optionally wctx / whr). Descope runs the configured flow, then posts the response back to the reply URL.
You can also pass tenant or login_hint (and related aliases) as query parameters so the flow can skip tenant discovery or pre-fill identity, similar to SAML login hints.
IdP-initiated
Every WS-Fed application exposes an IdP-initiated URL under the Identity Provider settings:
https://api.descope.com/v1/auth/wsfed/idp/initiate?app=<Application ID>Users open this URL, authenticate with Descope, and are returned to the configured reply URL — no RP redirect required first. Optional query parameters include tenant and login_hint.
Configuration reference
| Setting | Description |
|---|---|
| Application Name / ID / Description | App identity in Descope; ID is fixed after creation. |
| Flow Hosting URL | Descope flow users see when signing in. |
| Realm | Relying party realm (wtrealm). |
| Reply URL | Post-auth return URL (wreply). |
| Attribute / group mapping | Claims included in the WS-Fed response. |
| Force Authentication | Always run the login flow. |
| Logout / Error Redirect URLs | Post-logout and error landing pages. |
| IdP Metadata / Entity ID / SSO URL / Certificate | Values to configure on the relying party. |
| IdP-Initiated URL | Entry point for IdP-started SSO. |
Next steps
- Associate users (or tenants) with the app so only the right people can sign in — see Federated Apps.
- Manage apps from code with the Management SDKs.
- For OIDC or SAML instead, see OIDC and SAML.