WS-Federation (Web Services Federation) describes the management and brokering of trust relationships and security token exchange across Web services and organizational boundaries. WS-Federation is a part of the larger WS-Security framework. For example, WS-Federation builds on the Security Token Service (STS) by providing mechanisms that facilitate interactions. In the WS-Federation Model, an Identity Provider is a Security Token Service (STS). Service Providers depend on an Identity Provider or Security Token Service to do the user authentication. According to the Trust Brokering model defined in the WS-Trust specification, the subject (user) should authenticate themselves to the STS before obtaining a token. STS may use this authentication information when constructing the security token. For example, STS may populate the required claims based on the user name provided by the subject.
WSO2 Identity Server's passive security token service (Passive STS) is used as the WS-Federation implementation. The Passive STS is capable of issuing SAML 1.1 and 2.0 security tokens.
Before you begin
Sign in to the WSO2 Identity Server Management Console at
https://<Server Host>:9443/carbon using your
- Navigate to the Identity Provider section under Main > Identity menu-item.
- Click Add.
- Provide values for the following fields under the Basic Information section:
Field Description Sample Value Identity Provider Name
The Identity Provider Name must be unique as it is used as the primary identifier of the identity provider.
FacebookIdP, Twitter Display Name
The Display Name is used to identify the identity provider. If this is left blank, the Identity Provider Name is used. This is used in the login page when selecting the identity provider that you wish to use to log in to the service provider.
Facebook, Twitter Description The Description is added in the list of identity providers to provide more information on what the identity provider is. This is particularly useful in situations where there are many identity providers configured and a description is required to differentiate and identify them. This is the identity provider configuration. Federation Hub Identity Provider
Select the Federation Hub Identity Provider check-box to indicate if this points to an identity provider that acts as a federation hub. A federation hub is an identity provider that has multiple identity providers configured to it and can redirect users to the correct identity provider depending on their Home Realm identifier or their Identity Provider Name. When we have this check-box selected additional window will pop-up in the multi-option page in the first identity server to get the home realm identifier for the desired identity provider in the identity provider hub.
Selected Home Realm Identifier
The Home Realm Identifier value can be specified in each federated IDP and can send the Home Realm Identifier value as the “fidp” query parameter (e.g., fidp=googleIdp) in the authentication request by the service provider. The WSO2 Identity Server finds the IDP related to the “fidp” value and redirects the end user to the IDP directly rather than showing the SSO login page. By using this, you can avoid multi-option, in a multi-option scenario without redirecting to the multi-option page.
FB, TW Identity Provider Public Certificate
The Identity Provider Public Certificate is the public certificate belonging to the identity provider. Uploading this is necessary to authenticate the response from the identity provider. See Using Asymmetric Encryption in the WSO2 Product Administration Guide for more information on how public keys work and how to sign these keys by a certification authority.
This can be any certificate. If the identity provider is another Identity Server, this can be a
crtfile.To create the Identity Provider Certificate click here
Open your Command Line interface, traverse to the
<IS_HOME>/repository/resources/security/directory. Next, you must execute the following command.
Once this command is run, the wso2.crtfile is generated and can be found in the
<IS_HOME>/repository/resources/security/directory. Click Choose File and navigate to this location in order to obtain and upload this file.See Using Asymmetric Encryption in the WSO2 Product Administration Guide for more information.
The Alias is a value that has an equivalent value specified in the identity provider that we are configuring. This is required for authentication in some scenarios.
- Expand the WS-Federation (Passive) Configuration form.
Fill in the following fields where relevant.
Field Description Sample value Enable Passive STS Selecting this option enables Passive STS to be used as an authenticator for users provisioned to the Identity Server. Selected Default Selecting the Default checkbox signifies that Passive STS is the main/default form of authentication. This removes the selection made for any other Default checkboxes for other authenticators. Selected Passive STS Realm This is used as an identifier for the realm and can be any value. WSFederationHealthCare Passive STS URL
When sending the authentication request, there is a request for a security token generated by WS-Trust.
As long as the federated IdP is the WSO2 Identity Server, this URL must follow this format:
https://localhost:9443/passivests/ Passive STS User ID Location Select whether the User ID is found in 'Name Identifier' as part of the authentication request or if it is found among the claims. This specifies how the user is identified. User ID found in 'Name Identifier' Additional Query Parameters This is necessary if you are connecting to another Identity Server or application. Sometimes extra parameters are required by this IS or application so these can be specified here. paramName1=value1
Configuring hostname verification
In previous releases, Passive STS Single-Logout (SLO) requests for service providers were initiated without hostname verification which can impose a security risk. From IS 5.2.0 release onwards, certificate validation has been enforced and hostname verification is enabled by default. If you want to disable the hostname verification, configure the following property in the
<IS_HOME>/repository/conf/identity/identity.xml file under the
Note: If the certificate is self-signed, import the service provider's public key to the IS client trust store to ensure that the SSL handshake in the SLO request is successful. For more information on how to do this, see Managing Keystores with the UI in the WSO2 Product Administration Guide.