Securing OCC Calls

Information

  1. OCC calls are secured by standard, highly configurable Spring security mechanisms.
  2. A user who access the application is called a principal.
  3. A principal can be an external system like a backend or frontend application, or a mobile application.
  4. OCC uses a standard OAuth2 protocol.
  5. The OAuth 2.0 authorization framework is the default authorization framework for the commerce driven OCC (Omni Commerce Connect) Web Services.
  6. The key benefit of using OAuth 2.0 (compared to basic authentication, even over HTTPS) is that the API client does not have to save or, in some cases, even obtain the user’s credentials. Instead, access tokens are returned to the client that can use refresh tokens to obtain new access tokens once they have expired.
  7. Access tokens are credentials used to access protected resources. An access token is a string representing an authorization issued to the client. Tokens represent specific scopes and durations of access granted by the resource owner.
  8. Bearer Tokens are the predominant type of access token used with OAuth 2.0.
  9. Refresh tokens are credentials used to obtain access tokens. Refresh tokens are issued to the client by the authorization server and are used to obtain a new access token when the current access token becomes invalid or expires.
  10. Authentication means checking provided credentials. If credentials are valid, then the proper roles are assigned to a principal.
  11. Authorization means deciding if a principal can perform a given action. This is determined based on the assigned roles of the principal and also on other constraints, for example secure communication channel.

User Roles For OCC Calls

Authentication TypeRoles
AnonymousA non authenticated principal is assigned built-in ANONYMOUS role by default.
ClientsAll client application authenticated through OAuth2 token in the client credentials flow is assigned a specific role depending on client definition. While defining a client, make sure that the client is assigned either ROLE_CLIENT or ROLE_TRUSTED_CLIENT because these roles allow the client to access ycommercewebservices extension.
CustomersUsers authenticated using the OAuth2 token in the password flow, are assigned a list of roles that are received from a service layer. By default, CUSTOMERGROUP and CUSTOMERMANAGERGROUP roles are used.
GuestsFor guest user a built-in GUEST role is assigned.

Spring Security Configuration

  1. The OAuth2 Resource Server configuration and other security aspects are defined in the /ycommercewebservices/web/webroot/WEB-INF/config/common/security-spring.xml file.
  2. Configuration files specific for webservices version v2 is /ycommercewebservices/web/webroot/WEB-INF/config/v2/security-v2-spring.xml.
  3. OAuth configuration is stored in the Platform. Server is configured in the project. properties file of the oauth2 extension.
    1. To enable the authorization server, add the oauth2 extension entry into the localextensions.xml file:
      <extension name=”oauth2″ />
    2. By default, the web root is authorizationserver/ but we can change it using the oauth2.webroot property.
    3. To configure the oauth2 extension, in the local.properties file following properties are used.
      1. webservicescommons.required.channel
      2. oauthauthorizationserver.tokenServices.reuseRefreshToken
      3. oauth2.supportRefreshToken
      4. oauth2.refreshTokenValiditySeconds
      5. oauth2.cleanupAccessToken.maxRows
      6. oauth2.accessTokenValiditySeconds
  4. The authorization server exposes two endpoints:
    1. /oauth/authorize
    2. /oauth/token
  5. To make Spring Security work you have to add the springSecurityFilterChain to the web services filter chain as shown below in the configuration for v2(/ycommercewebservices/web/webroot/WEB-INF/config/v2/filter-config-v2-spring.xml)

       <bean id="commerceWebServicesFilterChainV2" class="de.hybris.platform.servicelayer.web.PlatformFilterChain">
        <constructor-arg>
            <ref bean="commerceWebServicesFilterChainListV2" />
        </constructor-arg>
    </bean>
    <alias name="defaultCommerceWebServicesFilterChainListV2" alias="commerceWebServicesFilterChainListV2" />
    <util:list id="defaultCommerceWebServicesFilterChainListV2">
        <!-- filter that catches and resolves exceptions thrown from other filters -->
        <ref bean="exceptionTranslationFilter" />
        <!-- generic platform filters -->
        <ref bean="log4jFilter" />
        <ref bean="restSessionFilterV2" />
        <!-- commerceWebservices filters -->
        <ref bean="baseSiteMatchingFilter" />
        <ref bean="commerceWebServicesSessionAttributesFilterV2" />
        <!-- Security -->
        <ref bean="springSecurityFilterChain" />
        <ref bean="userMatchingFilter" />
        <!-- Matching filters -->
        <ref bean="cartMatchingFilter" />
        <ref bean="guestRoleFilterV2" />
    </util:list>