Authenticating and Authorizing REST APIs

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

The requests that are sent via REST APIs are intercepted by tomcat valves and authenticated and authorized by an OSGI service. There are two OSGi services that provide the authentication and authorization service based on its own handlers.

• WSO2 Identity Server supports the following authentication handlers: 
  • OAuth2AccessTokenHandler
  • ClientCertificateBasedAuthenticationHandler 
  • BasicAuthenticationHandler 
• The authorization handler is based on the permission specified against a particular user role.  

Let's learn how to authenticate and authorize REST APIs: 

1. To enable the intercepting of services:
   1. Open the catalina-server.xml file found in the <IS_HOME>/repository/conf/tomcat directory. 

   2. Uncomment the following valves found under the <Engine name="Catalina"> tag.    

       <!-- 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"/-->

2. To specify the resources that you want to secure:

   1. Open the identity.xml file found in the  <IS_HOME>/repository/conf/identity directory. 

   2. Specify the resource that you want to secure under the <ResourceAccssControl> as given below. 

      Parameter	Description	Sample Value
      Resource context	This defines the resource context relative to the root context, which needs to be secured.	/api/identity/*
      secured	This specifies whether to enable or disable security in the given resource context.	true
      http-method	This defines the method as all, post, get, etc.	all
      Permissions	This defines the user role permission that is required to authorize the resource. You can enter multiple permission strings in a comma-separated list.	/permission/admin/login

      Example:

      <ResourceAccessControl>
          <Resource context="/api/identity/*" secured="true" http-method="all">
              <Permissions>/permission/admin/login</Permissions>
          </Resource>
      </ResourceAccessControl>

3. To configure intermediate certificate validation, configure the following in the identity.xml file as given below. 

   Parameter	Description	Sample Value
   IntermediateCertificateValidation	This defines whether intermediate certificate validation is enabled or not.	true
   IntermediateCerts	This specifies the context paths of the intermediate certificates.	localhost
   ExemptContext	This specifies the context paths that need to be exempted from intermediate certificate validation. It is recommended to add this parameter and leave it empty. This is because authentication might be broken in your system for the exempted contexts. However, if you still require context paths to be exempted, you can list the context paths as shown in the below example.

   Example:

   <IntermediateCertValidation enable="true">
        <IntermediateCerts>
            <CertCN>wso2isintcert</CertCN>
            <CertCN>localhost</CertCN>
        </IntermediateCerts>
        <ExemptContext>
            <Context>scim2</Context>
        </ExemptContext>
    </IntermediateCertValidation>

   When using intermediate certificate validation, CN will be taken as the username instead of retrieving from the header.