This documentation is for WSO2 Identity Server 5.3.0. View documentation for the latest release.
Configuring SAML 2.0 Web SSO - Identity Server 5.3.0 - WSO2 Documentation
||
Skip to end of metadata
Go to start of metadata

In a Single Sign On (SSO) system there are two roles; Service Providers and Identity Providers. The important characteristic of a single sign on 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 the those who try to access services of the service provider

The 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.

If you want to send query parameters that need to be updated dynamically with each SAML make sure WSO2 IS 5.3.0 is WUM updated until 2018-01-15 or beyond. For more information, see Query Parameter.

You can configure the SAML federated authenticator through one of the following ways:

Manual Configuration

  1. Enter your username and password to log in to the Management Console
  2. Navigate to the Main menu to access the Identity menu. Click Add under Identity Providers
    For more information, see Configuring an Identity Provider.  
  3. Fill in the details in the Basic Information section. 

  4. Expand the SAML2 Web SSO Configuration form and select Manual Configuration (selected by default). 
  5. Fill in the following fields where relevant. The * indicates required fields.
FieldDescriptionSample value
Enable SAML2 Web SSOSelecting this option enables SAML2 Web SSO to be used as an authenticator for users provisioned to the Identity Server.Selected
DefaultSelecting the Default checkbox 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
Identity Provider Entity IdThis 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.https://idp.example.org/idp/shibboleth
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
SSO URLThis is the URL that you want to send the SAML request to. This information should be taken from the external Identity provider.

https://localhost:8443/idp/profile/SAML2/Redirect/SSO

Enable Authentication Request SigningSelecting 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 EncryptionThis 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 LogoutSelect 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 SigningSelecting 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 for POST binding and SigAlg HTTP Parameter for REDIRECT binding. The expandable Signature Algorithms table that is given below lists the usable algorithms and their respective URIs that can be sent in the actual SAML request.

Default value is RSA with SHA1.
Digest Algorithm

Specifies the DigestMethod algorithm to be used in the Signature element for POST binding. The Digest Algorithms table that is given below lists the usable algorithms and their respective URIs that can be sent in the actual SAML request.

Default value is SHA1.
Attribute Consuming Service IndexSpecifies the AttributeConsumingServiceIndex attribute.By default, this field is empty. Therefore, this attribute is not sent with the request unless a value is defined.
Enable Force AuthenticationEnable force authentication or decide if force authentication needs to be enabled as per the request.
This affects the ForceAuthn attribute.
Default value is As Per Request.
Include Public CertificateIncludes the public certificate in the request.Selected by default.
Include Protocol BindingIncludes the ProtocolBinding attribute in the request.Selected by default.
Include NameID PolicyIncludes the NameIDPolicy element in the request. Selected by default.
Include Authentication ContextIncludes a new RequestedAuthnContext element in the request, or reuses the context that is sent via the 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. The Authentication Context Class table below lists the usable classes and their respective URIs that can be sent in the SAML  request   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.

  • If Comparison is set to exact or omitted, the resulting authentication context in the authentication statement MUST be the exact match of at least one of the authentication contexts specified.
  • If Comparison is set to minimum, then the resulting authentication context in the authentication statement MUST be at least as strong (as deemed by the responder) as one of the authentication contexts specified.
  • If Comparison is set to better, then the resulting authentication context in the authentication statement MUST be stronger (as deemed by the responder) than any one of the authentication contexts specified.
  • If Comparison is set to maximum, then the resulting authentication context in the authentication statement MUST be as strong as possible (as deemed by the responder) without exceeding the strength of at least one of the authentication contexts specified.
 Default value is Exact.
SAML2 Web SSO User Id LocationSelect whether the User ID is found in the 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 BindingSelect 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

Additional Query Parameters

This is necessary if you are connecting to another Identity Server or application. Sometimes extra parameters are required by WSO2 IS or application. Those values can be specified here so that they can be sent along with the SAML request.

If you want to send query parameters that need to be updated dynamically with each SAML request, you need to make sure WSO2 IS 5.3.0 is WUM updated until 2018-01-15 or beyond. The dynamic value needs to be defined within parenthesis.This value should be the key of the query parameter sent in the SAML request URL.
Example: locale={lang}

Multiple parameters can be defined by separation of query parameters using the & character.

Example: locale={lang}&scope=openid email profile
paramName1=value1

 Click here to expand for more information on security algorithms.

The following table lists out the security algorithms and their respective URI.

 Click here to expand for more information on digest algorithms.

The following table lists out the digest algorithms and their respective URI.

 Click here to expand for more information on authentication context classes.

The following table lists out the authentication context classes and their respective URI.

Authentication context class nameAuthentication context class URI
Internet Protocol urn:oasis:names:tc:SAML:2.0:ac:classes:InternetProtocol
Internet Protocol Password urn:oasis:names:tc:SAML:2.0:ac:classes:InternetProtocolPassword
Kerberosurn:oasis:names:tc:SAML:2.0:ac:classes:Kerberos
Mobile One Factor Unregistered urn:oasis:names:tc:SAML:2.0:ac:classes:MobileOneFactorUnregistered
Mobile Two Factor Unregisteredurn:oasis:names:tc:SAML:2.0:ac:classes:MobileTwoFactorUnregistered
Mobile One Factor Contract urn:oasis:names:tc:SAML:2.0:ac:classes:MobileOneFactorContract
Mobile Two Factor Contracturn:oasis:names:tc:SAML:2.0:ac:classes:MobileTwoFactorContract
Passwordurn:oasis:names:tc:SAML:2.0:ac:classes:Password
Password Protected Transporturn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport
Previous Session urn:oasis:names:tc:SAML:2.0:ac:classes:PreviousSession
Public Key X.509urn:oasis:names:tc:SAML:2.0:ac:classes:X509
Public Key PGP urn:oasis:names:tc:SAML:2.0:ac:classes:PGP
Public Key SPKI urn:oasis:names:tc:SAML:2.0:ac:classes:SPKI
Public Key XML Digital Signatureurn:oasis:names:tc:SAML:2.0:ac:classes:XMLDSig
Smartcard urn:oasis:names:tc:SAML:2.0:ac:classes:Smartcard
Smartcard PKIurn:oasis:names:tc:SAML:2.0:ac:classes:SmartcardPKI
Software PKI urn:oasis:names:tc:SAML:2.0:ac:classes:SoftwarePKI
Telephonyurn:oasis:names:tc:SAML:2.0:ac:classes:Telephony
Telephony (Nomadic)urn:oasis:names:tc:SAML:2.0:ac:classes:NomadTelephony
Telephony (Personalized) urn:oasis:names:tc:SAML:2.0:ac:classes:PersonalTelephony
Telephony (Authenticated) urn:oasis:names:tc:SAML:2.0:ac:classes:AuthenticatedTelephony
Secure Remote Password urn:oasis:names:tc:SAML:2.0:ac:classes:SecureRemotePassword
SSL/TLS Certificate­Based Client Authenticationurn:oasis:names:tc:SAML:2.0:ac:classes:TLSClient
Time Sync Token urn:oasis:names:tc:SAML:2.0:ac:classes:TimeSyncToken
Unspecifiedurn:oasis:names:tc:SAML:2.0:ac:classes:unspecified

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:

  1. Open the application-authentication.xml file found in the <IS_HOME>/repository/conf/identity folder.
  2. 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. This can impose a security risk. From the 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.


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 the 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 the SAML metadata upload, IS also supports SAML metadata download for the resident identity providers using the Management Console and URL.

  1. Enter your username and password to log on to the Management Console
  2. Navigate to the Main menu to access the Identity menu. Click Add under Identity Providers
    For more information, see Configuring an Identity Provider.  
  3. Fill in the details in the Basic Information section. 

  4. Expand the SAML2 Web SSO Configuration form and select Metadata File Configuration
    The following screen appears:
  5. Choose the correct IdP metadata file and click Register.

     Click here to view a sample Identity provider metadata configuration xml file
    Service provider metadata file
    <EntityDescriptor
    xmlns="urn:oasis:names:tc:SAML:2.0:metadata"
    entityID="example.com">
    <IDPSSODescriptor
    WantAuthnRequestsSigned="false"
    protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
    <KeyDescriptor use="signing">
    <KeyInfo xmlns="http://www.w3.org/2000/09/xmldsig#">
    <X509Data>
    <X509Certificate>
    -----BEGIN CERTIFICATE-----
    MIIC+jCCAmOgAwIBAgIJAParOnPwEkKjMA0GCSqGSIb3DQEBBQUAMIGKMQswCQYD
    VQQGEwJMSzEQMA4GA1UECBMHV2VzdGVybjEQMA4GA1UEBxMHQ29sb21ibzEWMBQG
    A1UEChMNU29mdHdhcmUgVmlldzERMA8GA1UECxMIVHJhaW5pbmcxLDAqBgNVBAMT
    I1NvZnR3YXJlIFZpZXcgQ2VydGlmaWNhdGUgQXV0aG9yaXR5MB4XDTEwMDcxMDA2
    MzMwM1oXDTI0MDMxODA2MzMwM1owdjELMAkGA1UEBhMCTEsxEDAOBgNVBAgTB1dl
    c3Rlcm4xEDAOBgNVBAcTB0NvbG9tYm8xFjAUBgNVBAoTDVNvZnR3YXJlIFZpZXcx
    ETAPBgNVBAsTCFRyYWluaW5nMRgwFgYDVQQDEw9NeSBUZXN0IFNlcnZpY2UwgZ8w
    DQYJKoZIhvcNAQEBBQADgY0AMIGJAoGBAN6bi0llFz+R+93nLLK5BmnuF48tbODp
    MBH7yGZ1/ESVUZoYm0GaPzg/ai3rX3r8BEr4TUrhhpKUKBpFxZvb2q+yREIeDEkD
    bHJuyVdS6hvtfa89WMJtwc7gwYYkY8AoVJ94gU54GP2B6XyNpgDTXPd0d3aH/Zt6
    69xGAVoe/0iPAgMBAAGjezB5MAkGA1UdEwQCMAAwHQYDVR0OBBYEFNAwSamhuJSw
    XG0SJnWdIVF1PkW9MB8GA1UdIwQYMBaAFNa3YmhDO7BOwbUqmYU1k/U6p/UUMCwG
    CWCGSAGG+EIBDQQfFh1PcGVuU1NMIEdlbmVyYXRlZCBDZXJ0aWZpY2F0ZTANBgkq
    hkiG9w0BAQUFAAOBgQBwwC5H+U0a+ps4tDCicHQfC2SXRTgF7PlAu2rLfmJ7jyoD
    X+lFEoWDUoE5qkTpMjsR1q/+2j9eTyi9xGj5sby4yFvmXf8jS5L6zMkkezSb6QAv
    tSHcLfefKeidq6NDBJ8DhWHi/zvC9YbT0KkCToEgvCTBpRZgdSFxTJcUksqoFA==
    -----END CERTIFICATE-----
    </X509Certificate>
    </X509Data>
    </KeyInfo>
    </KeyDescriptor>
    <KeyDescriptor use="encryption">
    <KeyInfo xmlns="http://www.w3.org/2000/09/xmldsig#">
    <X509Data>
    EwpDYWxpZm9ybmlhMRQwEgYDVQQHEwtTYW50YSBDbGFyYTEeMBwGA1UEChMVU3VuIE1pY3Jvc3lz
    dGVtcyBJbmMuMRowGAYDVQQLExFJZGVudGl0eSBTZXJ2aWNlczEcMBoGA1UEAxMTQ2VydGlmaWNh
    dGUgTWFuYWdlcjAeFw0wNzAzMDcyMjAxMTVaFw0xMDEyMDEyMjAxMTVaMDsxFDASBgNVBAoTC2V4
    YW1wbGUuY29tMSMwIQYDVQQDExpMb2FkQmFsYW5jZXItMy5leGFtcGxlLmNvbTCBnzANBgkqhkiG
    HREEETAPgQ1tYWxsYUBzdW4uY29tMA0GCSqGSIb3DQEBBAUAA0EAEgbmnOz2Rvpj9bludb9lEeVa
    OA46zRiyt4BPlbgIaFyG6P7GWSddMi/14EimQjjDbr4ZfvlEdPJmimHExZY3KQ==
     </X509Data>
    </KeyInfo>
    </KeyDescriptor>
    <ArtifactResolutionService 
               isDefault="true"
               index="0"
               Binding="urn:oasis:names:tc:SAML:2.0:bindings:SOAP"
               Location="https://example.com/SAML/Artifact"/>
    <SingleLogoutService
               Binding="urn:oasis:names:tc:SAML:2.0:bindings:SOAP"
               Location="https://example.com/SAML/SLO/SOAP"/>
    <SingleLogoutService
               Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"
               Location="https://example.com/SAML/SLO/Browser"
     ResponseLocation="https://example.com/SAML/SLO/Response"/>
    <SingleLogoutService
    Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"/>
    <SingleLogoutService
    Binding="urn:oasis:names:tc:SAML:2.0:bindings:SOAP"/>
    <ManageNameIDService
    Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"
    ResponseLocation="https://example.com:9443/amserver/IDPMniRedirect/metaAlias/idp"/>
    <ManageNameIDService
    Binding="urn:oasis:names:tc:SAML:2.0:bindings:SOAP"
    Location="https://example.com:9443/amserver/IDPMniSoap/metaAlias/idp"/>
    <NameIDFormat>
    urn:oasis:names:tc:SAML:2.0:nameid-format:persistent
    </NameIDFormat>
    <NameIDFormat>
    urn:oasis:names:tc:SAML:2.0:nameid-format:transient
    </NameIDFormat>
    <SingleSignOnService
    Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"
    Location="https://example.com:9443/amserver/SSORedirect/metaAlias/idp"/>
    <SingleSignOnService
    Binding="urn:oasis:names:tc:SAML:2.0:bindings:SOAP"
    Location="https://example.example.com:9443/amserver/SSOSoap/metaAlias/idp"/>
    </IDPSSODescriptor>
    </EntityDescriptor>

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 below:

  1. Open the application-authentication.xml file found in the <IS_HOME>/repository/conf/identity folder.
  2. 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.

Related Topics
  • No labels