Authorization in Liberty determines whether a user has access to a certain role within the system.

Open Liberty The latest information about authorization in Liberty is available on the Open Liberty website.

Authorization specifies access rights to resources. It usually follows authentication that confirms an identity. Whereas authentication answers the question: Are you who you say you are?; authorization answers the question: Do you have permission to do what you are trying to do?

Authorization for administrative functions

When an entity attempts to access a resource, the authorization service determines whether that entity has the required rights to access the resource. This concept holds true whether an entity is accessing an application or performing administrative functions. The main difference between authorizing access to an application and access to an administrative function lies in how the users are mapped to roles. For authorization of applications, use the application-bnd element in the server.xml file or the ibm-application-bnd.xml/xmi file to map the users to roles. For authorization of administrative functions, use the administrator-role element in the server.xml file to map the users to the administrator role. For more information about administrative security, see Connecting to Liberty by using JMX.

Authorization for applications

The following diagram describes how authorization works for applications. The authorization service checks the mappings of roles to users in the configuration files of the application and server, then grants or rejects the access request.

As the diagram shows, the web container contacts the authorization service, which checks the ibm-application-bnd.xml/xmi and server.xml files to determine the security roles. The Authorization service then checks these roles against the authorization table before sending a response back to the web container.

Figure 1. Overview of authorization process
authorization flowchart
  1. An authorization is made when an entity attempts to access a resource in an application that is served by Liberty. The web container calls the authorization service to determine whether a user has permission to access a certain resource, given a set of one or more required roles. The required roles are determined by the auth-constraint elements in the deployment descriptor and @ServletSecurity annotations.
  2. The authorization service determines what objects the required role is mapped to. This step is accomplished by processing the mappings that are defined in the ibm-application-bnd.xmi file or the ibm-application-bnd.xml file, and the application-bnd element of the server.xml file. The mappings from these two sources are merged. If the same role is present in both sources, only the role mapping in the server.xml file is used. The advantage of using the server.xml file for mapping roles to users is that your application does not need to be packaged into an EAR file and it is easier to update. Alternatively, using the ibm-application-bnd.xmi/xml file makes your application portable to other servers and other WebSphere® Application Server traditional servers that do not support the server.xml file.
  3. If the required role is mapped to the EVERYONE special subject, then the authorization service returns immediately to allow anyone access. If the role is mapped to the ALL_AUTHENTICATED_USERS special subject and the user is authenticated, then the authorization service grants access to the user. If none of these conditions are met, then the authorization service determines what users and groups are mapped to the required role. The authorization service grants access to the resource if the user is mapped to the required role or if the user is part of a group that is mapped to the role.
  4. The authorization service returns a result back to the web container to indicate whether the user is granted or denied access.

Special subjects

When you map entities to roles, you can map a special subject instead of a specific user or group. A special subject is an extension to the concept of a subject. A special subject can represent a group of users that fall under a specific category.

The following two types of special subjects are available:
  • EVERYONE: represents any entity on the system, which means that no security is available because everyone is allowed access and you are not prompted to enter credentials.
  • ALL_AUTHENTICATED_USERS: represents any entity that successfully authenticates to the server.
To map a special subject to a user, update either the ibm-application-bnd.xmi/xml file or the server.xml file, where the application-bnd is under the application element. In this example, the role that is named AllAuthenticated is mapped to the special subject ALL_AUTHENTICATED_USERS:
           <security-role name="AllAuthenticated">
               <special-subject type="ALL_AUTHENTICATED_USERS" />

See Configuring authorization for applications in Liberty.

Access IDs and authorization

When you authorize a user or group, the server needs a way to uniquely identify that user or group. The unique ID of the user and group serve this purpose and are used to build the authorization configuration. These IDs are determined by the user registry implementation: the unique user ID is the value of getUniqueUserId(), and the unique group ID is the value of getUniqueGroupId(). You can also choose to explicitly specify an access ID for the user or group in the authorization configuration. These explicit access IDs are used instead of the values that are returned by the user registry implementation. To specify an access ID in the ibm-application-bnd.xml/xmi file or the server.xml file, where the application-bnd is under the application element, use the access-id attribute for the user or group element.

In this example, an access ID is specified for the user Bob and the group developers:
           <security-role name="Employee">
               <user name="Bob" access-id="user:MyRealm/Bob"/>
               <group name="developers" access-id="group:myRealm/developers"/>
Note: The access-id attribute is used for the authorization check. If it is not specified, it is determined from the registry that is configured by using the user or group name. However, you must specify the access-id attribute as shown in the example when the users or groups do not belong to the active registry, such as when you are using a programmatic login, JSON Web Token (JWT), or MicroProfile JWT (mpJwt).


OAuth is an open standard for delegated authorization. With the OAuth authorization framework, a user can grant a third-party application access to their information stored with another HTTP service without sharing their access permissions or the full extent of their data. For more information on how you can use OAuth for authorization in Liberty, see the OAuth documentation.

Authorization for applications when role mapping binding is not provided

When the role mapping binding information for a protected application is not provided, the default authorization engine takes the role name that is protecting the resource as the group name associated with that role. So for example, if the role name is manager, then a user who belongs to a manager group has access to that resource. This applies only when no application bind information, in the server.xml or the application binding file, is specified for the application: For example, adding this binding disables the security role to group binding:

<application type="war" id="myapp" name="myapp" 	location="${server.config.dir}/apps/myapp.war">
	     <security-role name="anyAppRoleName"/>
Note: For an authorization to be successful with a group name in the user registry, the role name must match the full or unique name of the group in the registry that is configured and not the short name. For example, if short name of the group is swGroup but the full or unique name in the user registry is CN=swGroup,o=company,c=us, you need to specify CN=swGroup,o=company,c=us as the role name for the authorization to succeed.