This site contains the documentation that is relevant to older WSO2 product versions and offerings.
For the latest WSO2 documentation, go to https://wso2.com/documentation/.
Configuring SAML 2.0 Web SSO
In a single sign-on (SSO) system there are two roles; Service Providers and Identity Providers. The important characteristic of an SSO system is the pre-defined trust relationship between the service providers and the identity providers. Service providers trust the assertions issued by the identity providers and the identity providers issue assertions based on the results of authentication and authorization of principles which access services on the service provider's side.
SAML 2.0 web browser-based single-sign-on profile is defined under the SAML 2.0 Profiles specification. In a web browser-based SSO system, the flow can be started by the user either by attempting to access a service at the service provider, or by directly accessing the identity provider itself.
To navigate to the federated authenticators configuration section, do the following.
- Sign in. Enter your username and password to log on to the Management Console.
- Navigate to the Main menu to access the Identity menu. Click Add under Identity Providers.
For more information, see Adding and Configuring an Identity Provider. Fill in the details in the Basic Information section.
Expand the SAML2 Web SSO Configuration form. The following appears.
SAML configuration information can be entered through one of the following ways:
Manual Configuration
- Select the Manual Configuration. (selected by default)
- Fill in the following fields where relevant. The * indicates required fields.
| Field | Description | Sample value |
|---|---|---|
| Enable SAML2 Web SSO | Selecting this option enables SAML2 Web SSO to be used as an authenticator for users provisioned to the Identity Server. | Selected |
| Default | Selecting the Default check box signifies that SAML2 Web SSO is the main/default form of authentication. This removes the selection made for any other Default checkboxes for other authenticators. | Selected |
| Service Provider Entity Id | This is the entity Id of the Identity Server. This can be any value but when you configure a service provider in the external IDP you should give the same value as the Service Provider Entity Id. | wso2is |
| NameID format | This is the NameID format to be used in the SAML request. By default, it has | urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified |
| Select Mode | Select the mode to decide the input method for SAML configuration. You can have a manual configuration or Metadata data configuration where an .xml metadata file is uploaded. | Manual configuration (is selected by default) |
| Identity Provider Entity Id | This is basically the <Issuer> value of the SAML2 response from the identity provider you are configuring. This value must be a unique string among identity providers inside the same tenant. This information should be taken from the external Identity Provider. In order to enable the <Issuer> validation in the SAML2 response from the IdP, add following configuration to <AuthenticatorConfig name="SAMLSSOAuthenticator" enabled="true">
...
<Parameter name="VerifyAssertionIssuer">true</Parameter>
...
</AuthenticatorConfig>
| https://idp.example.org/idp/shibboleth |
| SSO URL | This is the URL that you want to send the SAML request to. This information should be taken from the external Identity Provider. | |
| Enable Authentication Request Signing | Selecting this checkbox enables you to sign the authentication request. If this is enabled, you must sign the request using the private key of the identity provider. | Selected |
| Enable Assertion Encryption | This is a security feature where you can encrypt the SAML2 Assertions returned after authentication. So basically, the response must be encrypted when this is enabled. | Selected |
| Enable Assertion Signing | Select Enable Assertion Signing to sign the SAML2 Assertions returned after the authentication. SAML2 relying party components expect these assertions to be signed by the Identity Server. | Selected |
| Enable Logout | Select Enable Single Logout so that all sessions are terminated once the user signs out from one server. | Selected |
| Logout URL | If the external IDP support for logout you can select Enable Logout. Then you can set the URL of the external IDP, where you need to send the logout request, under Logout URL. If you do not set a value for this it will simply return to the SSO URL. | https://localhost:8443/idp/samlsso/logout |
| Enable Logout Request Signing | Selecting this checkbox enables you to sign the logout request. | Selected |
| Enable Authentication Response Signing | Select Enable Authentication Response Signing to sign the SAML2 responses returned after the authentication. | Selected |
| Signature Algorithm | Specifies the ‘SignatureMethod’ algorithm to be used in the ‘Signature’ element in POST binding and “SigAlg” HTTP Parameter in REDIRECT binding. The expandable Signature Algorithms table below lists the usable algorithms and their respective URIs that will be sent in the actual SAMLRequest. | Default value is RSA with SHA1. |
| Digest Algorithm | Specifies the ‘DigestMethod’ algorithm to be used in the ‘Signature’ element in POST binding. The Digest Algorithms table below lists the usable algorithms and their respective URIs that will be sent in the actual SAMLRequest. | Default value is SHA1. |
| Attribute Consuming Service Index | Specifies the ‘AttributeConsumingServiceIndex’ attribute. | By default this would be empty, therefore that attribute would not be sent unless filled. |
| Enable Force Authentication | Enable force authentication or decide from the incoming request. This affects ‘ForceAuthn’ attribute. | Default value is As Per Request. |
| Include Public Certificate | Include the public certificate in the request. | Selected by default. |
| Include Protocol Binding | Include ‘ProtocolBinding’ attribute in the request. | Selected by default. |
| Include NameID Policy | Include ‘NameIDPolicy’ element in the request. | Selected by default. |
| Include Authentication Context | Include a new ‘RequestedAuthnContext’ element in the request, or reuse from the incoming request. | Default value is Yes. |
| Authentication Context Class | Choose an Authentication Context Class Reference (AuthnContextClassRef) to be included in the requested authentication context from the Identity Server which specifies the authentication context requirements of authentication statements returned in the response. Authentication Context Class table below lists the usable classes and their respective URIs that will be sent in the SAMLRequest from the Identity Server to trusted IdP. | Default value is “PasswordProtectedTransport”. |
| Authentication Context Comparison Level | Choose the Requested Authentication Context ‘Comparison’ attribute to be sent which specifies the comparison method used to evaluate the requested context classes or statements.
| Default value is “Exact”. |
| SAML2 Web SSO User Id Location | Select whether the User ID is found in 'Name Identifier' or if it is found among claims. If the user ID is found among the claims, it can override the User ID Claim URI configuration in the identity provider claim mapping section. | User ID found among claims |
| HTTP Binding | Select the HTTP binding details that are relevant for your scenario. This refers to how the request is sent to the identity provider. HTTP-Redirect and HTTP-POST are standard means of sending the request. If you select As Per Request it can handle any type of request. | HTTP-POST |
| Response Authentication Context Class | Select As Per Response to pass the AuthnContextClassRef received from the configured identity provider to the service provider. Select Default to pass the default AuthnContextClassRef instead. The AuthnContextClassRef specifies how the user has been authenticated by the IdP (e.g. via username/password login, via certificate etc.) | As Per Response |
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. These will be sent along with the SAML request. If you want to send query parameters that can be dynamically updated with each SAML request, you need to apply the WUM update for WSO2 IS 5.4.0, released on the 21st of February 2018. You can also define multiple query parameters by specifying the parameters separated using the & character. For example, You can deploy a WUM update into production only if you have a paid subscription. If you do not have a paid subscription, you can use this functionality when the next version of WSO2 IS is released. | paramName1=value1 |
Metadata File Configuration
About Metadata upload
When configuring a service provider (SP) or federated Identity Provider (Federated IdP), the user is required to enter configuration data to facilitate exchanging authentication and authorization data between entities in a standard way. Apart from manual entering of configuration data, the Identity Server 5.3.0 provides the facility to upload configuration data using a metadata xml file or referring to metadata xml file located in a predetermined URL. These two methods of uploading configuration data enables faster entry of configuration data because it allows the user to use the same metadata xml file for multiple instances of entity configuration. In addition to SAML metadata upload, IS also supports SAML metadata download for resident Identity providers using Management Console and URL.
- Select Metadata File Configuration.
The following screen appears:
Choose the correct IdP metadata file and click Register.
Configure ACL URL in a production environment
The default assertion consumer URL that is sent with the SAML request includes the local domain and default port. In a production environment, you may need to change the assertion consumer URL. To do this, follow the steps given below:
- Open the
application-authentication.xml file found in the<IS_HOME>/repository/conf/identityfolder. Add the following property and update the assertion consumer URL as required.
<AuthenticatorConfig name="SAMLSSOAuthenticator" enabled="true"> <Parameter name="SAMLSSOAssertionConsumerUrl">https://localhost:9443/commonauth</Parameter> </AuthenticatorConfig>
Configuring hostname verification
In previous releases, SAML 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 Server\SSOService tag.
<SLOHostNameVerificationEnabled>false</SLOHostNameVerificationEnabled>
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.
- Identity Federation is part of the process of configuring an identity provider. For more information on how to configure an identity provider, see Configuring an Identity Provider.
- See Configuring Shibboleth IdP as a Trusted Identity Provider for a sample of using SAML2 Web SSO configuration.