com.sap.cloud.security.oauth2

## Class OAuthAuthorizationFilter

- java.lang.Object
- - com.sap.cloud.security.oauth2.OAuthAuthorizationFilter

- All Implemented Interfaces:
    Filter

      public class OAuthAuthorizationFilter
      extends Object
      implements Filter

  Performs the protected resource access check by retrieving from the Authorization Server the scopes associated with the given Access Token, and checks the Token validity.

  You can easily integrate the OAuth 2.0 protection for the resources with the OAuthAuthorizationFilter by using the standard servlet filter description in the `web.xml`.

  Declaring a servlet filter in the `web.xml` consists of three steps:

  1. Specify the filter class - com.sap.cloud.security.oauth2.OAuthAuthorizationFilter
  2. Map between either a servlet or a URL pattern with the filter
  3. Specifying the initial parameters.

  The init parameters that can be defined during the filter declaration are:

  > scope - (optional) The protected resource can be mapped to a certain scope or to any scopes. Thus, when specifying a web application resource protected by the OAuth protocol, one must also supply the name of the scope under which this resource is accessible, or leave it unspecified in case the recourse is public. In case of unspecified scope parameter only authentication will be performed. The scope parameter accepts only a single value that must conform to the valid scope name syntax specified in Section 3.3 in RFC6749. This means that for each scope and mapped resources a different filter declaration has to be provided.

  > http-method - (optional) If the HTTP method (GET, POST, PUT or DELETE) is not provided in the filter declaration, the filter will be applied for all HTTP methods.

  > user-principal - (optional) This parameter shows whether or not the resource owner's user id is passed as the user principal name in the request in case of successful authorization. If not specified in the filter declaration the default value is false. If true and successfully authorization, the resource owner's user id will be passed as a HttpServletRequest attribute with name `"user_id"` and as a user principle and can be retrieved by `"request.getUserPrincipal()"` . If false and successful authorization, the the resource owner's user id value will be only passed as HttpServletRequest attribute with name `"user_id"`.

  > no-session - (optional) This parameter controls whether the login session is invalidated after the request is processed.

  Example use of this filter in web.xml file is shown in the code snippet below:

  >      <filter>
  >        <display-name>OAuth scope definition for viewing a photo album</display-name>
  >        <filter-name>OAuthViewPhotosScopeFilter</filter-name>
  >        <filter-class>
  >          com.sap.cloud.security.oauth2.OAuthAuthorizationFilter
  >        </filter-class>
  >        <init-param>
  >          <param-name>scope</param-name>
  >          <param-value>view-photos</param-value>
  >        </init-param>
  >        <init-param>
  >          <param-name>http-method</param-name>
  >          <param-value>get</param-value>
  >        </init-param>
  >        <init-param>
  >          <param-name>user-principal</param-name>
  >          <param-value>true</param-value>
  >        </init-param>
  >      </filter>

  >      <filter>
  >        <display-name>OAuth scope definition for viewing a photo album</display-name>
  >        <filter-name>OAuthViewPhotosScopeFilter</filter-name>
  >        <filter-class>
  >          com.sap.cloud.security.oauth2.OAuthAuthorizationFilter
  >        </filter-class>
  >        <init-param>
  >          <param-name>scope</param-name>
  >          <param-value>view-photos upload-photos</param-value>
  >        </init-param>
  >        <init-param>
  >          <param-name>http-method</param-name>
  >          <param-value>get post put delete</param-value>
  >        </init-param>
  >        <init-param>
  >          <param-name>no-session</param-name>
  >          <param-value>true</param-value>
  >        </init-param>
  >      </filter>

  The given example is provided for illustration purposes only.

  When the resources, protected by the filter is requested, the Access Token must be passed by using the HTTP "Authorization" request header field. The value of this header must be the token type and access token value. The currently supported token type is `"bearer"`.

  For example the header could look like:

  >      "Authorization: Bearer mF_9.B5f-4.1JqM"

  The given example is provided for illustration purposes only.

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `OAuthAuthorizationFilter()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `destroy()`
    `void` | `doFilter(ServletRequest request, ServletResponse response, FilterChain chain)`
    `void` | `init(FilterConfig config)`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### OAuthAuthorizationFilter

          public OAuthAuthorizationFilter()

  - ### Method Detail

    - #### doFilter

          public void doFilter(ServletRequest request,
                      ServletResponse response,
                      FilterChain chain)
                        throws IOException,
                               ServletException

      Specified by:
        `doFilter` in interface `Filter`
      Parameters:
        `response` - - On failure one of the following error codes would be sent.
        Internal server error (500) - Unexpected error in the Resource server, DB connection is unavailable, OAuth destination is not found or cannot get destination http client.
        Unauthorized (401) - Invalid access token on missing access token in the HTTP "Authorization" request header.
        Access is forbidden (403) - In case of failed authorization
      Throws:
        `IOException`
        `ServletException`
      See Also:
        `doFilter(ServletRequest request, ServletResponse response, FilterChain chain)`

    - #### init

          public void init(FilterConfig config)
                    throws ServletException

      Specified by:
        `init` in interface `Filter`
      Throws:
        `ServletException`

    - #### destroy

          public void destroy()

      Specified by:
        `destroy` in interface `Filter`

Copyright © 2016 SAP. All Rights Reserved.