guide access control
Access-Control is a central and important aspect of Security. It consists of two major aspects:
-
Authentication (Who tries to access?)
-
Authorization (Is the one accessing allowed to do what he wants to do?)
Definition:
Authentication is the verification that somebody interacting with the system is the actual subject for whom he claims to be.
The one authenticated is properly called subject or principal. There are two forms of principals you need to distinguish while designing your authentication: human users and autonomous systems. While e.g. a Kerberos/SPNEGO Single-Sign-On makes sense for human users, it is pointless for authenticating autonomous systems. For simplicity, we use the common term user to refer to any principal even though it may not be a human (e.g. in case of a service call from an external system).
To prove the authenticity, the user provides some secret called credentials. The most simple form of credentials is a password.
|
Note
|
Please never implement your own authentication mechanism or credential store. You have to be aware of implicit demands such as salting and hashing credentials, password life-cycle with recovery, expiry, and renewal including email notification confirmation tokens, central password policies, etc. This is the domain of identity and access management (IAM). There are various existing products for IAM that already solve the problems better than you could ever implement it yourselve. In a business context you will typically already find a system for this purpose that you have to integrate (e.g. via JWT and OAuth). In case you have the freedom of choice, we recommend using keycloak. |
We recommend using JWT when possible. For KISS, also try to avoid combining multiple authentication mechanisms (form based, basic-auth, SAMLv2, OAuth, etc.) within the same application (for different URLs). Please note that inside an identity and access management (IAM) you have many different options for authentication. In case you are in charge of making decisions considere the following options according to your requirements and demands (esp. security):
For spring, check the Spring Security
For quarkus, check the Quarkus Authentication
Definition:
Authorization is the verification that an authenticated user is allowed to perform the operation he intends to invoke.
For clarification we also want to give a common understanding of related terms that have no unique definition and consistent usage in the wild.
| Term | Meaning and comment |
|---|---|
Permission |
A permission is an object that allows a principal to perform an operation in the system. This permission can be granted (give) or revoked (taken away). Sometimes people also use the term right what is actually wrong as a right (such as the right to be free) can not be revoked. |
Group |
We use the term group in this context for an object that contains permissions. A group may also contain other groups. Then the group represents the set of all recursively contained permissions. |
Role |
We consider a role as a specific form of group that also contains permissions. A role identifies a specific function of a principal. A user can act in a role. For simple scenarios a principal has a single role associated. In more complex situations a principal can have multiple roles but has only one active role at a time that he can choose out of his assigned roles. For KISS it is sometimes sufficient to avoid this by creating multiple accounts for the few users with multiple roles. Otherwise at least avoid switching roles at run-time in clients as this may cause problems with related states. Simply restart the client with the new role as parameter in case the user wants to switch his role. |
Access Control |
Any permission, group, role, etc., which declares a control for access management. |
For the access model we give the following suggestions:
-
Each Access Control (permission, group, role, …) is uniquely identified by a human readable string.
-
We create a unique permission for each use-case.
-
We define groups that combine permissions to typical and useful sets for the users.
-
We define roles as specific groups as required by our business demands.
-
We allow to associate users with a list of Access Controls.
-
For authorization of an implemented use case we determine the required permission. Furthermore, we determine the current user and verify that the required permission is contained in the tree spanned by all his associated Access Controls. If the user does not have the permission we throw a security exception and thus abort the operation and transaction.
-
We avoid negative permissions, that is a user has no permission by default and only those granted to him explicitly give him additional permission for specific things. Permissions granted can not be reduced by other permissions.
-
Technically we consider permissions as a secret of the application. Administrators shall not fiddle with individual permissions but grant them via groups. So the access management provides a list of strings identifying the Access Controls of a user. The individual application itself contains these Access Controls in a structured way, whereas each group forms a permission tree.
As stated above each Access Control is uniquely identified by a human readable string. This string should follow the naming convention:
«app-id».«local-name»«local-name» again follows the convention:
«verb»«object»| Segment | Description | Example |
|---|---|---|
«app-id» |
Is a unique technical but human readable string of the application (or microservice). It shall not contain special characters and especially no dot or whitespace. We recommend to use |
|
«verb» |
The action that is to be performed on «object». We use |
|
«object» |
The affected object or entity. Shall be named according to your data-model |
|
So as an example shop.FindProduct will reflect the permission to search and retrieve a Product in the shop application. The group shop.ReadMasterData may combine all permissions to read master-data from the shop. However, also a group shop.Admin may exist for the Admin role of the shop application. Here the «local-name» is Admin that does not follow the «verb»«object» schema.
The module devon4j-security provides ready-to-use code based on spring-security that makes your life a lot easier.
The diagram shows the model of devon4j-security that separates two different aspects:
-
The Identity- and Access-Management is provided by according products and typically already available in the enterprise landscape (e.g. an active directory). It provides a hierarchy of primary access control objects (roles and groups) of a user. An administrator can grant and revoke permissions (indirectly) via this way.
-
The application security defines a hierarchy of secondary access control objects (groups and permissions). This is done by configuration owned by the application (see following section). The "API" is defined by the IDs of the primary access control objects that will be referenced from the Identity- and Access-Management.
In your application simply extend AccessControlConfig to configure your access control objects as code and reference it from your use-cases. An example config may look like this:
@Named
public class ApplicationAccessControlConfig extends AccessControlConfig {
public static final String APP_ID = "MyApp";
private static final String PREFIX = APP_ID + ".";
public static final String PERMISSION_FIND_OFFER = PREFIX + "FindOffer";
public static final String PERMISSION_SAVE_OFFER = PREFIX + "SaveOffer";
public static final String PERMISSION_DELETE_OFFER = PREFIX + "DeleteOffer";
public static final String PERMISSION_FIND_PRODUCT = PREFIX + "FindProduct";
public static final String PERMISSION_SAVE_PRODUCT = PREFIX + "SaveProduct";
public static final String PERMISSION_DELETE_PRODUCT = PREFIX + "DeleteProduct";
public static final String GROUP_READ_MASTER_DATA = PREFIX + "ReadMasterData";
public static final String GROUP_MANAGER = PREFIX + "Manager";
public static final String GROUP_ADMIN = PREFIX + "Admin";
public ApplicationAccessControlConfig() {
super();
AccessControlGroup readMasterData = group(GROUP_READ_MASTER_DATA, PERMISSION_FIND_OFFER, PERMISSION_FIND_PRODUCT);
AccessControlGroup manager = group(GROUP_MANAGER, readMasterData, PERMISSION_SAVE_OFFER, PERMISSION_SAVE_PRODUCT);
AccessControlGroup admin = group(GROUP_ADMIN, manager, PERMISSION_DELETE_OFFER, PERMISSION_DELETE_PRODUCT);
}
}In your use-case you can now reference a permission like this:
@Named
public class UcSafeOfferImpl extends ApplicationUc implements UcSafeOffer {
@Override
@RolesAllowed(ApplicationAccessControlConfig.PERMISSION_SAVE_OFFER)
public OfferEto save(OfferEto offer) { ... }
...
}Role-based Access Control (RBAC) is commonly used for authorization. JSR 250 defines a number of common annotations to secure your application.
-
javax.annotation.security.PermitAllspecifies that no access control is required to invoke the specified method(s). -
javax.annotation.security.DenyAllspecifies that no access controls are allowed to invoke the specified method(s). -
javax.annotation.security.RolesAllowedspecifies that only a list of access controls are allowed to invoke the specified method(s). -
javax.annotation.security.DeclareRolesdefines roles for security checking. -
javax.annotation.security.RunAsspecifies the RunAs role for the given components.
@PermitAll, @Denyall, and @RolesAllowed annotations can be applied to both class and method.
A method-level annotation will override the behaviour of class-level annotation. Using multiple annotations of those 3 is not valid.
// invalid
@PermitAll
@DenyAll
public String foo()
// invalid and compilation fails
@RolesAllowed("admin")
@RolesAllowed("user")
public String bar()
// OK
@RolesAllowed("admin", "user")
public String bar()Please note that when specifying multiple arguments to @RolesAllowed those are combined with OR (and not with AND).
So if the user has any of the specified access controls, he will be able to access the method.
As a best practice avoid specifying string literals to @RolesAllowed.
Instead define a class with all access controls as constants and reference them from there.
This class is typically called ApplicationAccessControlConfig in devonfw.
In many complicated cases where @PermitAll @DenyAll @RolesAllowed are insufficient e.g. a method should be accessed by a user in role A and not in role B at the same time, you have to verify the user role directly in the method. You can use SecurityContext class to get further needed information.
Spring Security also supports authorization on method level. To use it, you need to add the spring-security-config dependency. If you use Spring Boot, the dependency spring-boot-starter-security already includes spring-security-config. Then you can configure as follows:
-
prePostEnabledproperty enables Spring Security pre/post annotations.@PreAuthorizeand@PostAuthorizeannotations provide expression-based access control. See more here -
securedEnabledproperty determines if the@Securedannotation should be enabled.@Securedcan be used similarly as@RollesAllowed. -
jsr250Enabledproperty allows us to use the JSR-250 annotations such as@RolesAllowed.
@Configuration
@EnableGlobalMethodSecurity(
prePostEnabled = true,
securedEnabled = true,
jsr250Enabled = true)
public class MethodSecurityConfig
extends GlobalMethodSecurityConfiguration {
}A further read about the whole concept of Spring Security Authorization can be found here.
Quarkus comes with built-in security to allow for RBAC based on the common security annotations @RolesAllowed, @DenyAll, @PermitAll on REST endpoints and CDI beans. Quarkus also provides the io.quarkus.security.Authenticated annotation that will permit any authenticated user to access the resource (equivalent to @RolesAllowed("**")).
See data permissions
The access-control-schema.xml approach is deprecated. The documentation can still be found in access control schema.
This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).
