io.vertx.ext.auth.authorization.Authorization Maven / Gradle / Ivy

Go to download
/********************************************************************************
 * Copyright (c) 2019 Stephane Bastian
 *
 * This program and the accompanying materials are made available under the 2
 * terms of the Eclipse Public License 2.0 which is available at
 * http://www.eclipse.org/legal/epl-2.0.
 *
 * SPDX-License-Identifier: EPL-2.0 3
 *
 * Contributors: 4
 *   Stephane Bastian - initial API and implementation
 ********************************************************************************/
package io.vertx.ext.auth.authorization;

import io.vertx.codegen.annotations.GenIgnore;
import io.vertx.codegen.annotations.VertxGen;
import io.vertx.core.json.JsonObject;
import io.vertx.ext.auth.User;
import io.vertx.ext.auth.authorization.impl.AuthorizationConverter;

import static io.vertx.codegen.annotations.GenIgnore.PERMITTED_TYPE;

/**
 * Interface representing any kind of authorization such as:
 * 
 *   Role based authorization
 *   
Permission based authorization
 *   
Logical authorization (AND, OR, NOT)
 *   
Time based authorization (ie: allow access the last 5 days of the month, from 8am till 10am, etc.)
 *   
Context based authorization (ie: allow access if the ip address is 'xxx.xxx.xxx.xxx')
 *   
Custom based authorization (ie: based on a script or hard-coded code specific to an application)
 *   
etc.
 * 
 * The following implementations are provided out of the box:
 * 
 *   {@link AndAuthorization}
 *   
{@link NotAuthorization}
 *   
{@link OrAuthorization}
 *   
{@link PermissionBasedAuthorization}
 *   
{@link RoleBasedAuthorization}
 *   
{@link WildcardPermissionBasedAuthorization}
 * 
 *
 * @author Stephane Bastian
 */
@VertxGen(concrete = false)
public interface Authorization {

  /**
   * this methods verifies whether or not the authorization match the specified
   * context.
   *
   * @param context the context.
   * @return true if there's a match.
   */
  boolean match(AuthorizationContext context);

  /**
   * this methods verifies whether or not the authorization match the specified
   * user. Internally a basic context is created with the user and the method
   * delegates to {@link #match(AuthorizationContext)}
   *
   * @param user the user.
   * @return true if there's a match
   */
  @GenIgnore(PERMITTED_TYPE)
  default boolean match(User user) {
    return match(AuthorizationContext.create(user));
  }

  /**
   * this method verifies whether or not the authorization implies the specified
   * authorization.
   * 
Note that it doesn't always mean an exact match. For instance,
   * in the case of a {@link WildcardPermissionBasedAuthorization}, this method
   * may return true even if the permissions are different
   * 
WildcardPermissionBasedAuthorization.create('*').verify(WildcardPermissionBasedAuthorization.create('anypermission'))
   * would return true
   *
   * @param authorization the authorization.
   * @return true if implies the argument.
   */
  boolean verify(Authorization authorization);

  default JsonObject toJson() {
    return AuthorizationConverter.encode(this);
  }
}