Authenticating and Authorizing REST APIs

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 with REST APIs, tomcat valves are used to intercept these 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 its own handlers. You can write your own handlers for both authentication and authorization and register them in OSGI. The WSO2 Identity Server has the following three out-of-the-box authentication handlers:

OAuth2AccessTokenHandler
ClientCertificateBasedAuthenticationHandler
BasicAuthenticationHandler

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

Secure resources

To secure REST services in the WSO2 Identity Server, follow the steps below.

Open the catalina-server.xml file found in the <IS_HOME>/repository/conf/tomcat folder.

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

Open the identity.xml file found in the <IS_HOME>/repository/conf/identity folder.
Use the following code block to specify the resource that you want to secure.
```
<ResourceAccessControl>
    <Resource context="/api/identity/*" secured="true" http-method="all">
        <Permissions>/permission/admin/login</Permissions>
    </Resource>
</ResourceAccessControl>
```
- 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.

Configure intermediate certificate validation

To use this feature, apply the 3863 WUM update for WSO2 Identity Server 5.6.0 using the WSO2 Update Manager (WUM). To deploy a WUM update into production, you need to have a paid subscription. If you do not have a paid subscription, you can use this feature with the next version of WSO2 Identity Server when it is released. For more information on updating WSO2 Identity Server using WUM, see Getting Started with WUM.

Configuring intermediate certificate validation enables you to restrict certificates that are used during mutualSSL authentication to certificates that are signed by the defined issuers(cert_cns).

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

Parameter	Description	Sample Value
IntermediateCertificateValidation	Defines whether intermediate certificate validation is enabled or not.	`true`
IntermediateCerts	Specifies the context paths of the intermediate certificates. Multiple `<CertCN>` elements can be used for multiple certificates.	`localhost`
ExemptContext	Specifies the context paths that needs to be excempted from intermediate certificate validation. Multiple `<Context>` elements can be used for multiple contexts.

Example:

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

When using intermediate certificate validation, note that CN will be taken as the username instead of retrieving it from the header therefore, the incoming certificate request CN should ideally be the username of the user who is sending the request.

The certificate CN should be in the following formats for the following cases.

If the user is in the primary userstore, the incoming cert CN should be just the <username> e.g., john.
If the user is in a secondary userstore, the incoming cert CN should be <userstore_domain>/<username> e.g., SECONDARY/john.
If the user is not a super tenant and belongs to the primary userstore, the incoming cert CN should be <username@tenant_doman> e.g., john@abc.com.
If the user is not a super tenant and belongs to a secondary userstore, the incoming cert CN should be <userstore_domain>/<username@tenant_doman> e.g., SECONDARY/john@abc.com.