This documentation is for WSO2 Identity Server 5.3.0 . View documentation for the latest release.
Skip to end of metadata
Go to start of metadata

This section guides you through securing REST services and how requests to REST APIs are authenticated and authorized in the WSO2 Identity Server.  

When sending requests to REST APIs, tomcat valves are used to intercept the requests, and an OSGI service is used to authenticate and authorize the request. There are two OSGi services that provide the authentication and authorization service based on the handlers. You can write your own handlers for both authentication and authorization, and then register them in OSGI. WSO2 Identity Server provides the following three default authentication handlers:

  • OAuth2AccessTokenHandler
  • ClientCertificateBasedAuthenticationHandler 
  • BasicAuthenticationHandler

Authentication handlers are picked based on the canHandle() method and their priority.


If you apply the WUM update released on the 14th of May 2018 for WSO2 Identity Server 5.3.0, you can do the following with regard to authentication handlers:

  • Disable an authentication handler at the system level.

     Click here for instructions:
    1. Edit the <IS_HOME>/repository/conf/identity/identity.xml file.
    2. Under <EventListeners>, set the enable property of a required event listener to false.

      For example, if you want to disable ClientCertificateBasedAuthenticationHandler at the system level, you need to set the enable property of the org.wso2.carbon.identity.auth.service.handler.impl.ClientCertificateBasedAuthenticationHandler event listener to false as follows:

      <EventListener enable="false"
            orderId="1000" type="org.wso2.carbon.identity.core.handler.AbstractIdentityMessageHandler"/>
  • Enforce required authentication mechanisms per resource. For example, depending on your requirement you can consider protecting a particular resource only with basic authentication.

    If you have not applied the WUM update, you cannot enforce required authentication mechanisms per resource because authentication handlers will be picked dynamically based on context.

     Click here for instructions:
    1. Edit the <IS_HOME>/repository/conf/identity/identity.xml file.
    2. For a required resource context under <ResourceAccessControl>, use the allowed-auth-handlers attribute and specify all the authentication handlers that you want to enforce on the resource. For example, if you want to enforce basic authentication and OAuth authentication for the (.*)/usermanagement/v1/user/(.*) resource context, you need to specify the allowed-auth-handlers attribute values as follows:

         <Resource context="(.*)/usermanagement/v1/user/(.*)" http-method="all" secured="true" allowed-auth-handlers="BasicAuthentication,OAuthAuthentication">
  • Change the priority order of any authentication handler at the system level.

     Click here for instructions:
    1. Edit the <IS_HOME>/repository/conf/identity/identity.xml file.
    2. Use the orderId property to specify an appropriate priority order value as follows:

      <EventListener enable="true"
            orderId="1" type="org.wso2.carbon.identity.core.handler.AbstractIdentityMessageHandler"/>

The authorization handler is based on the specified permission against a particular user role. You can write your own handler for authorization as well. 

Securing REST services in WSO2 Identity Server

Follow the steps below to secure REST services in WSO2 Identity Server:

  1. Open the catalina-server.xml file found in the <IS_HOME>/repository/conf/tomcat folder.
  2. Uncomment the following valves found under the <Engine name="Catalina"> tag, to enable each service to intercept requests. 

     <!-- Authentication and Authorization valve for the rest apis and we can configure context for this in identity.xml  -->
     <!--Valve className="org.wso2.carbon.identity.auth.valve.AuthenticationValve"/>
     <Valve className = "org.wso2.carbon.identity.authz.valve.AuthorizationValve"/-->
  3. Open the identity.xml file found in the  <IS_HOME>/repository/conf/identity folder.
  4. Use the following code block to specify the resource that you want to secure. 

        <Resource context="/api/identity/*" secured="true" http-method="all">
    • Resource context: Specify which resource context(relative to the root context) must be secured.

    • secured: Specify true or false to enable to enable and disable security in this context. 
    • http-method: Specify "all" or the type of method (e.g., "post", "get" etc.)
    • <Permissions>: Define which permission strings should be assigned your role to authorize this resource, by specifying the permission strings in a comma separated list.
  • No labels