This documentation is for WSO2 Identity Server 5.2.0. View documentation for the latest release.
Customizing the Authentication Endpoint - Identity Server 5.2.0 - WSO2 Documentation
||
Skip to end of metadata
Go to start of metadata

The authentication endpoint is the authentication URL used in authentication requests. The following sections discuss methods of customizing this endpoint for various scenarios.

Customizing the authentication endpoint URL

The authentication endpoint URL is the location in your web application that contains authentication related pages.

Follow the steps below to customize the authentication endpoint URL:

  1. Edit the <IS_HOME>/repository/conf/identity/application-authentication.xml file, and change the value of the following parameter depending on the URL that the web application should run.

    <AuthenticationEndpointURL>/sso/login</AuthenticationEndpointURL>

    For example, If you specify the value as /sso/login, the web application runs on https://<host_name>:port_number>/sso/login.

    Note

    If you do not change the default value of the <AuthenticationEndpointURL> parameter, accessing the dashboard redirects you to the WSO2 Identity Server management console.

  2. Run the web application on the new authentication endpoint URL.

Controlling the request parameters going to the authentication endpoint

Additional request parameters can be added and customized for the request sent to the authentication endpoint. To customize this, uncomment the following configurations in the <IS_HOME>/repository/conf/identity/application-authentication.xml file, under the ApplicationAuthentication element (which is the root element).

<!--AuthenticationEndpointQueryParams action="exclude"-->
<!--AuthenticationEndpointQueryParam name="username"/-->
<!--AuthenticationEndpointQueryParam name="password"/-->
<!--/AuthenticationEndpointQueryParams-->

Note: In the above configuration, username and password are just given as examples. You can configure any query parameter here for your request and customize it according to your specifications.

Loading tenants into the dropdown in the login page of the authentication endpoint web application

This section is useful in scenarios where there are multiple tenants used, where users can login to web applications with their credentials for their specified tenants. For instance, for a user in the test.com tenant with the username test1, the user would have to enter the full username as test1@test.com in order to login. Enabling this feature will load all the available active tenants onto a dropdown list on the login page of the web application that the authentication endpoint points to. This means that the test1 user mentioned above can simply select the tenant he/she belongs to (test.com) from the dropdown list and only needs to enter the username (i.e., test1) in the username textbox on the login page, without having to type it with "@tenant-domain".  

Do the following configurations to enable this feature.  

  1. Open the <IS_HOME>/repository/conf/tomcat/catalina-server.xml file and ensure that the clientAuth attribute in the Connector tag is set to “want” as shown below. This is done to disable the certificate authentication on certain occasions (like when working on mobile apps). This makes two-way SSL authentication optional.

    clientAuth="want"

    The .jar file enabling usage of Mutual SSL is shipped with IS by default from IS versions 5.1.0 and upwards. The org.wso2.carbon.identity.authenticator.mutualssl_X.X.X.jar file can be found in the <IS_HOME>/repository/components/plugins directory.

  2. Open the <IS_HOME>/repository/conf/security/authenticators.xml file and add the disabled="false" attribute within the <Authenticator> tag for the MutualSSLAuthenticator to enable the Mutual SSL Authenticator. 

    <!-- Authenticator Configurations for MutualSSLAuthenticator-->
    <Authenticator name="MutualSSLAuthenticator" disabled="false">
        <Priority>5</Priority>
        <Config>
            <Parameter name="UsernameHeader">UserName</Parameter>
            <Parameter name="WhiteListEnabled">false</Parameter>
            <Parameter name="WhiteList"/>
        </Config>
    </Authenticator>
  3. If the SAML2SSOAuthenticator is enabled (disabled="false") in the <IS_HOME>/repository/conf/security/authenticators.xml file, set its priority to 0. Otherwise ignore this step.

    <Authenticator name="SAML2SSOAuthenticator" disabled="false">
    	<Priority>0</Priority>
    	...
    </Authenticator>
  4. Add the following configuration into the <IS_HOME>/repository/conf/identity/application-authentication.xml file under the ApplicationAuthentication tag.

    <TenantDomainDropDownEnabled>true</TenantDomainDropDownEnabled>
    <TenantDataListenerURLs>
    	<TenantDataListenerURL>
    		/authenticationendpoint/tenantlistrefresher.do
    	</TenantDataListenerURL>
    </TenantDataListenerURLs>

    Note: When configuring the TenantDataListenerURL tag, note the following.

    • In a clustered setup that has multiple authentication endpoint web applications hosted, list all of them under the TenantDataListenerURL tag.

    • For authentication endpoint web applications hosted outside the WSO2 Identity Server or in other nodes of a cluster, add the absolute URL within the TenantDataListenerURL tag.

  5. Restart the server using one of the following commands.

    • Windowswso2server.bat

    • Linux/Unixsh wso2server.sh

  6. Once the server is restarted, the authenticationendpoint.war file is deployed. The <IS_HOME>/repository/conf/identity/EndpointConfig.properties file has to be changed with the required values for properties. The following are the default values for the properties to be used in this file.

    tenantListEnabled=false
    hostname.verification.enabled=true
    mutual.ssl.username=admin
    client.keyStore=./repository/resources/security/wso2carbon.jks
    Carbon.Security.KeyStore.Password=wso2carbon
    client.trustStore=./repository/resources/security/client-truststore.jks
    Carbon.Security.TrustStore.Password=wso2carbon
    #identity.server.serviceURL=https://localhost:9443/services/
    username.header=UserName

    Do the following updates to this configuration.

    1. Set tenantListEnabled to true in order to enable the tenants to display as a list.
    2. For the mutual.ssl.username property, set the username that is to be used for mutual SSL authentication. This user needs to have permission to list down tenants. You can add a new username here provided that you create a user with that username and grant the following permissions to the role of the user.

      Super Admin Permissions > Manage > Monitor > Tenants > List

    3. Paths for client keystore and truststore can be relative paths or absolute paths. The default paths point to the keystore and truststore of the Identity Server itself. A new keystore can be created and used for the client if necessary, however, you must set the passwords for client.keyStore.password and client.trustStore.password appropriately.

    Note:If you are hosting the autheticationendpoint.war webapp outside the Identity Server (i.e in a different Tomcat or WSO2 Application Server), then you cannot use the <IS_HOME>/repository/conf/identity/EndpointConfig.properties file because the webapp does not have access to this file. Instead, the same property file can be found at <WebApp_HOME>/authenticationendpoint/WEB-INF/classes/EndpointConfig.properties.

    In this scenario, do the following:

    • Open the <WebApp_HOME>/authenticationendpoint/WEB-INF/classes/EndpointConfig.properties file and provide the full URL to WSO2 Identity Server’s admin services endpoint in the  identity.server.serviceURL property following the format below.

       identity.server.serviceURL=https://<ip>:<port>/services
    • Copy the org.wso2.carbon.identity.application.authentication.endpoint.util-5.0.7.jar file and paste it in the <WebApp_HOME>/authenticationendpoint/WEB-INF/lib folder.


      • If you have applied the WSO2-CARBON-PATCH-4.4.0-0073 security patch, copy the .jar file found in the <CARBON_PATCH_HOME>/patch0073 folder.
      • If you have not applied the WSO2-CARBON-PATCH, copy the .jar file found in the <IS_HOME>/repository/components/plugins folder.
  7. For mutual SSL authentication, the public certificate of the Identity Server has to be imported to the truststore of the client and the public certificate of the client has to be imported to the client-truststore of Identity Server.

    Sample commands

    The following two commands are examples if you are using the keystore and client-truststore of the Identity Server itself for the client. This is executed from the <IS_HOME>/repository/resources/security directory.

    keytool -export -alias wso2carbon -file carbon_public2.crt -keystore wso2carbon.jks -storepass wso2carbon
    keytool -import -trustcacerts -alias carbon -file carbon_public2.crt -keystore client-truststore.jks -storepass wso2carbon

Removing the tenant list from the login page

If it is required to remove the tenant domain dropdown list in SSO Login page, follow the steps below.

  1. Shutdown the server if it is already started.
  2. Set the property tenantListEnabled=false in the EndpointConfig.properties file.

    • If you are hosting the authenticationendpoint.war webapp within WSO2 Identity Server, set this property in the <IS_HOME>/repository/conf/identity/EndpointConfig.properties file.
       

    • If you are hosting it outside the WSO2 Identity Server (i.e., external Tomcat or WSO2 Application Server), set this property in the <IS_HOME>/repository/deployment/server/webapps/authenticationendpoint/WEB-INF/classes/EndpointConfig.properties file.  
  3. Set TenantDomainDropDownEnabled parameter to false in the <IS_HOME>/repository/conf/identity/application-authentication.xml file.

    <TenantDomainDropDownEnabled>false</TenantDomainDropDownEnabled>
  4. If the MutualSSLAuthenticator is only used for the purpose of listing tenant domains in the drop down, disable it in the <IS_HOME>/repository/conf/security/authenticators.xml file.

    <Authenticator name="MutualSSLAuthenticator" disabled="true">
  5. Restart the server.

Customizing the authentication endpoint webapp to support browser back button action and access via bookmarked sign-in page

This section describes how you can customize the authentication endpoint webapp to seamlessly handle the following actions:

  • When you sign in to an authentication endpoint webapp and then click the back button on the browser, you should be redirected to the appropriate sign-in page.
  • When you click a bookmarked authentication endpoint webapp URL, you should be redirected to the appropriate sign-in page.

Let's take a look at how this can be done.

First you need to follow the steps below:

  1. Clone the authentication browser back button handler git repo and navigate to the source directory.
  2. Execute the following command to build the CustomLoginEndpointUtils-1.0.0.jar:

    mvn clean install
  3. Copy the CustomLoginEndpointUtils-1.0.0.jar to the <IS_HOME>/repository/components/dropins directory.
  4. Copy the check_session_id.jsp file from the artifacts directory of the cloned git repo to the <IS_HOME>/repository/deployment/server/webapps/authenticationendpoint directory.
  5. Edit the <IS_HOME>/repository/deployment/server/webapps/authenticationendpoint/WEB-INF/web.xml file and add the following entries:

        <servlet>
            <servlet-name>check_session_id.do</servlet-name>
            <jsp-file>/check_session_id.jsp</jsp-file>
        </servlet>
        ...
        <servlet-mapping>
            <servlet-name>check_session_id.do</servlet-name>
            <url-pattern>/check_session_id.do</url-pattern>
        </servlet-mapping>
    
  6. Edit the <IS_HOME>/repository/deployment/server/webapps/authenticationendpoint/login.jsp file and update the <head> element as follows:

    <head>
     …
     <script>
     function checkSessionKey() {
     $.ajax({
     type: “GET”,
     url: ‘check_session_id.do?sessionDataKey=’ + getParameterByName(‘sessionDataKey’) + ‘&relyingParty=’ + getParameterByName(‘relyingParty’) + ‘&tenantDomain=’ + getParameterByName(‘tenantDomain’),
     success: function (data) {
     var response = JSON.parse(data);
     if (response && response.status == “redirect” && response.redirectUrl && response.redirectUrl.length > 0) {
     window.location.href = response.redirectUrl;
     }
     }
     });
     }
    function getParameterByName(name, url) {
     if (!url) {
     url = window.location.href;
     }
     name = name.replace(/[\[\]]/g, “\\$&”);
     var regex = new RegExp(“[?&]” + name + “(=([^&#]*)|&|#|$)”),
     results = regex.exec(url);
     if (!results) return null;
     if (!results[2]) return ‘’;
     return decodeURIComponent(results[2].replace(/\+/g, “ “));
     }
     </script>
     </head>
    {code}
    In the same login.jsp file add below change to <body> element.
     <body onload=”checkSessionKey()”>
    Now add the following line to the as the last line in the <script> element in same login.jsp.
    {code:xml}
     …
     window.onunload = function(){};
     </script>
    </body>
     </html>

    If necessary, you can get the complete login.jsp page content with all the changes specified above from here.

  7. Restart WSO2 Identity Server.

Next, you need to add a registry resource that contains the redirect URLs of different service providers. To do that, follow the steps below: 

Note

  • These configurations have to be specified per-tenant.
  • You need to do the configuration after logging on to the service provider's tenant admin console.
  1. Start WSO2 Identity Server and access the management console via https://localhost:9443/carbon/.

  2. On the management console, click Main and then click Browse under Registry. This displays the registry browser.


  3. Go to /_system/config/identity/config in the registry browser.

    Once you navigate to /_system/config/identity/config, follow the steps below to add a registry resource.
  4. Click Add Resource

  5. On the Add Resource screen, specify the following values:
    • Method : Select Create text content

    • Name :  relyingPartyRedirectUrls.

  6. Click Add. You will see that the created registry resource is added. 

  7. Click the added resource (i.e., relyingPartyRedirectUrls). You will see the Properties section.

  8. Click the + sign at the right hand corner of the Properties section. This allows you to add a property to the resource. 
  9. Click Add New Property.

  10. Enter the relying party name as the Name and specify the redirect URL as the Value

    The redirect URL should be the URL that you want to be redirected to when you click the back button on the browser.


    When you specify the relying party name and the redirect URL, be sure to keep the following in mind:

    <Oauth2_client_id>=<login_redirect_url>
    <Issuer Name>=<login_redirect_url>


    Also note the following:

    Relying party for SAML = Issuer Name

    Relying party for Oauth2 = OAuth Client Key


    Following are sample values that you can specify as the Name and Value when you add a new property:

    Name : wso2.my.dashboard

    Value : https://localhost:9443/dashboard/index.jag

  11. Click Add. 

    Note

    If you want this to work in the http mode when you use Internet Explorer as the browser, you need to disable AJAX response caching using the following funcvtion:

    function checkSessionKey() {
                    $.ajax({
    		    cache: false,
                        type: "GET",
                        url: 'check_session_id.do?sessionDataKey=' + getParameterByName('sessionDataKey') + '&relyingParty=' + getParameterByName('relyingParty') + '&tenantDomain=' + getParameterByName('tenantDomain'),
                        success: function (data) {
                            var response = JSON.parse(data);
                            if (response && response.status == "redirect" && response.redirectUrl && response.redirectUrl.length > 0) {
                                window.location.href = response.redirectUrl;
                            }
                        }
                    });
                }

Now you can try out the following actions:

  • Sign in to an authentication endpoint webapp and then click the back button on the browser.
  • Click a bookmarked authentication endpoint webapp URL.

You will see that you are redirected to the appropriate sign-in page when you try out the actions specified above.


  • No labels