AuthzGroupService API

The AuthzGroupService manages authorization groups (realms) in Sakai. This service allows you to check if a user is allowed to perform a particular function in a context.

Overview

Package: org.sakaiproject.authz.api The AuthzGroupService provides:

Authorization group (realm) management
Role-based permission checking
User membership and role assignment
Function-based access control
Provider integration for external groups

This service doesn’t verify that user IDs returned are still valid. If you need to ensure a user exists, check with UserDirectoryService. Deleted user entries in AuthzGroups should be cleaned up but currently may persist.

Key Concepts

AuthzGroup (Realm): A container for users, roles, and permissions (e.g., /site/biology-101)
Role: A named set of permissions (e.g., “Student”, “Instructor”, “maintain”)
Function: A specific permission (e.g., “site.upd”, “content.read”, “assignment.submit”)
Member: A user with a role in an AuthzGroup
Provider: External source for group membership (e.g., course roster system)

Constants

APPLICATION_ID

String

default:"sakai:authzGroup"

Application identifier for the authorization service

REFERENCE_ROOT

String

default:"/realm"

Root path for realm references

ANON_ROLE

String

default:".anon"

Standard role name for anonymous users

AUTH_ROLE

String

default:".auth"

Standard role name for authenticated users

Security Functions

SECURE_ADD_AUTHZ_GROUP

String

default:"realm.add"

Permission to add an AuthzGroup

SECURE_REMOVE_AUTHZ_GROUP

String

default:"realm.del"

Permission to remove an AuthzGroup

SECURE_UPDATE_AUTHZ_GROUP

String

default:"realm.upd"

Permission to update an AuthzGroup

SECURE_UPDATE_OWN_AUTHZ_GROUP

String

default:"realm.upd.own"

Permission to update one’s own relationship in an AuthzGroup

SECURE_JOIN_AUTHZ_GROUP

String

default:"realm.join"

Permission to join an AuthzGroup

SECURE_UNJOIN_AUTHZ_GROUP

String

default:"realm.unjoin"

Permission to unjoin an AuthzGroup

Core Methods

AuthzGroup Access

getAuthzGroup

AuthzGroup getAuthzGroup(String id) throws GroupNotDefinedException

Access an AuthzGroup by ID.

String

required

The AuthzGroup ID (e.g., “/site/biology-101”)

AuthzGroup

The AuthzGroup object

Throws:

GroupNotDefinedException - if not found

Example:

try {
    AuthzGroup realm = authzGroupService.getAuthzGroup("/site/biology-101");
    
    // Get members
    Set<Member> members = realm.getMembers();
    for (Member member : members) {
        String userId = member.getUserId();
        String role = member.getRole().getId();
        System.out.println(userId + " has role " + role);
    }
    
    // Get roles
    Set<Role> roles = realm.getRoles();
    for (Role role : roles) {
        Set<String> functions = role.getAllowedFunctions();
    }
} catch (GroupNotDefinedException e) {
    // AuthzGroup not found
}

getAuthzGroups

List<AuthzGroup> getAuthzGroups(String criteria, PagingPosition page)

Access a list of AuthzGroups matching criteria.

The group objects returned will not have associated roles loaded. To save a realm, retrieve it with getAuthzGroup(String).

criteria

String

Selection criteria: match this string in ID or provider group ID

page

PagingPosition

Subset of items to return

List<AuthzGroup>

List of AuthzGroups matching criteria (naturally sorted)

countAuthzGroups

int countAuthzGroups(String criteria)

Count AuthzGroups matching criteria.

criteria

String

Selection criteria

int

Count of matching AuthzGroups

AuthzGroup Creation

addAuthzGroup

AuthzGroup addAuthzGroup(String id) 
    throws GroupIdInvalidException, GroupAlreadyDefinedException, AuthzPermissionException

Add a new AuthzGroup.

String

required

The AuthzGroup ID

AuthzGroup

The new AuthzGroup

Throws:

GroupIdInvalidException - if the ID is invalid
GroupAlreadyDefinedException - if the ID is already used
AuthzPermissionException - if current user lacks permission

Example:

try {
    AuthzGroup realm = authzGroupService.addAuthzGroup("/site/new-site");
    
    // Add a role
    Role instructorRole = realm.addRole("Instructor");
    instructorRole.allowFunction("site.upd");
    instructorRole.allowFunction("content.new");
    
    // Add a member
    realm.addMember(userId, "Instructor", true, false);
    
    // Save
    authzGroupService.save(realm);
} catch (GroupAlreadyDefinedException e) {
    // Realm already exists
}

addAuthzGroup (Copy)

AuthzGroup addAuthzGroup(String id, AuthzGroup other, String maintainUserId)
    throws GroupIdInvalidException, GroupAlreadyDefinedException, AuthzPermissionException

Add a new AuthzGroup as a copy of another, giving a user maintain access.

String

required

The new AuthzGroup ID

other

AuthzGroup

required

The AuthzGroup to copy

maintainUserId

String

Optional user ID to get maintain access, or null

AuthzGroup

The new AuthzGroup object

newAuthzGroup

AuthzGroup newAuthzGroup(String id, AuthzGroup other, String maintainUserId)
    throws GroupAlreadyDefinedException

Create a new AuthzGroup without saving it. Can be saved later with save().

String

required

The AuthzGroup ID

other

AuthzGroup

AuthzGroup to copy (or null)

maintainUserId

String

Optional user ID to get maintain access

AuthzGroup

The new unsaved AuthzGroup object

AuthzGroup Modification

save

void save(AuthzGroup azGroup) 
    throws GroupNotDefinedException, AuthzPermissionException

Save changes to an AuthzGroup. The AuthzGroup must already exist.

This method refreshes current memberships based on the group’s associated provider, if any. This updates site memberships based on course enrollment records.

azGroup

AuthzGroup

required

The AuthzGroup to save

Throws:

GroupNotDefinedException - if the AuthzGroup ID is not defined
AuthzPermissionException - if current user lacks permission

Example:

try {
    AuthzGroup realm = authzGroupService.getAuthzGroup("/site/biology-101");
    
    // Add a new member
    realm.addMember(studentId, "Student", true, false);
    
    // Update a role's permissions
    Role taRole = realm.getRole("Teaching Assistant");
    taRole.allowFunction("assignment.grade");
    
    // Save changes
    authzGroupService.save(realm);
} catch (AuthzPermissionException e) {
    // User cannot update this realm
}

AuthzGroup Removal

removeAuthzGroup

void removeAuthzGroup(AuthzGroup azGroup) 
    throws AuthzPermissionException, AuthzRealmLockException

Remove an AuthzGroup.

azGroup

AuthzGroup

required

The AuthzGroup to remove

Throws:

AuthzPermissionException - if current user lacks permission
AuthzRealmLockException - if the group has a lock preventing removal

removeAuthzGroup (by ID)

void removeAuthzGroup(String id) 
    throws AuthzPermissionException, AuthzRealmLockException

Remove the AuthzGroup with this ID (fails quietly if not found).

String

required

The AuthzGroup ID

Permission Checking

isAllowed (Single Group)

boolean isAllowed(String userId, String function, String azGroupId)

Test if a user is allowed to perform a function in an AuthzGroup.

userId

String

required

The user ID

function

String

required

The function to check (e.g., “site.upd”, “content.read”)

azGroupId

String

required

The AuthzGroup ID to consult

boolean

true if allowed, false otherwise

Example:

String userId = sessionManager.getCurrentSessionUserId();
String siteId = "/site/biology-101";

if (authzGroupService.isAllowed(userId, "site.upd", siteId)) {
    // User can update this site
}

if (authzGroupService.isAllowed(userId, "assignment.grade", siteId)) {
    // User can grade assignments in this site
}

isAllowed (Multiple Groups)

boolean isAllowed(String userId, String function, Collection<String> azGroups)

Test if a user is allowed to perform a function in any of the named AuthzGroups.

userId

String

required

The user ID

function

String

required

The function to check

azGroups

Collection<String>

required

Collection of AuthzGroup IDs to consult

boolean

true if allowed in any group, false otherwise

Example:

// Check if user can access any section's resources
List<String> sectionRealms = Arrays.asList(
    "/site/bio-101/group/section-a",
    "/site/bio-101/group/section-b"
);

if (authzGroupService.isAllowed(userId, "content.read", sectionRealms)) {
    // User can read content in at least one section
}

User and Role Queries

getUsersIsAllowed

Set<String> getUsersIsAllowed(String function, Collection<String> azGroups)

Get the set of user IDs who are allowed to perform a function in the named AuthzGroups.

function

String

required

The function to check

azGroups

Collection<String>

required

Collection of AuthzGroup IDs to consult

Set<String>

Set of user IDs who are allowed to perform the function

Example:

// Get all instructors in a site
Set<String> instructors = authzGroupService.getUsersIsAllowed(
    "site.upd",
    Collections.singleton("/site/biology-101")
);

for (String instructorId : instructors) {
    User user = userDirectoryService.getUser(instructorId);
    System.out.println("Instructor: " + user.getDisplayName());
}

getUsersIsAllowedByGroup

Set<String[]> getUsersIsAllowedByGroup(String function, Collection<String> azGroups)

Get user IDs per group who are allowed to perform a function.

function

String

required

The function to check

azGroups

Collection<String>

required

Collection of AuthzGroup IDs (null to search all)

Set<String[]>

Set of String arrays [userId, realmId] for users allowed to perform the function

Example:

// Get all graders organized by section
Set<String[]> gradersBySection = authzGroupService.getUsersIsAllowedByGroup(
    "assignment.grade",
    Arrays.asList(
        "/site/bio-101/group/section-a",
        "/site/bio-101/group/section-b"
    )
);

for (String[] entry : gradersBySection) {
    String userId = entry[0];
    String realmId = entry[1];
    System.out.println(userId + " can grade in " + realmId);
}

getUserCountIsAllowed

Map<String, Integer> getUserCountIsAllowed(String function, Collection<String> azGroups)

Get the number of users per group allowed to perform a function.

function

String

required

The function to check

azGroups

Collection<String>

required

Collection of AuthzGroup IDs (null to search all)

Map<String, Integer>

Map of authzGroupId to user count

getAuthzGroupsIsAllowed

Set<String> getAuthzGroupsIsAllowed(String userId, String function, 
                                    Collection<String> azGroups)

Get the set of AuthzGroup IDs where a user is allowed to perform a function.

userId

String

required

The user ID

function

String

required

The function to check

azGroups

Collection<String>

Collection of AuthzGroup IDs to search (null to search all)

Set<String>

Set of AuthzGroup IDs where user is allowed the function

Example:

// Find all sites where user can grade assignments
Set<String> gradingSites = authzGroupService.getAuthzGroupsIsAllowed(
    userId,
    "assignment.grade",
    null  // Search all sites
);

for (String realmId : gradingSites) {
    // Extract site ID from realm ID
    String siteId = realmId.substring("/site/".length());
    Site site = siteService.getSite(siteId);
    System.out.println("Can grade in: " + site.getTitle());
}

getUserRole

String getUserRole(String userId, String azGroupId)

Get the role name for a user in an AuthzGroup.

userId

String

required

The user ID

azGroupId

String

required

The AuthzGroup ID

String

The role name, or null if user is not a member

Example:

String role = authzGroupService.getUserRole(userId, "/site/biology-101");
if (role != null) {
    System.out.println("User has role: " + role);
} else {
    System.out.println("User is not a member");
}

getUserRoles

Map<String, String> getUserRoles(String userId, Collection<String> azGroupIds)

Get all role names for a user in a set of AuthzGroups.

userId

String

required

The user ID

azGroupIds

Collection<String>

Collection of AuthzGroup IDs to search (null or empty to search all)

Map<String, String>

Map of AuthzGroup ID to role name for groups where user is a member

getUsersRole

Map<String, String> getUsersRole(Collection<String> userIds, String azGroupId)

Get role names for multiple users in one AuthzGroup.

userIds

Collection<String>

required

Collection of user IDs

azGroupId

String

required

The AuthzGroup ID

Map<String, String>

Map of userId to role name (only includes active members)

getAllowedFunctions

Set<String> getAllowedFunctions(String role, Collection<String> azGroups)

Get functions that users with a role in these AuthzGroups can perform.

role

String

required

The role name

azGroups

Collection<String>

required

Collection of AuthzGroup IDs

Set<String>

Set of function names

Membership Management

joinGroup

void joinGroup(String authzGroupId, String role) 
    throws GroupNotDefinedException, AuthzPermissionException, AuthzRealmLockException

Cause the current user to join an AuthzGroup with a role.

authzGroupId

String

required

The AuthzGroup ID

role

String

required

The role name

Throws:

GroupNotDefinedException - if authzGroupId or role not defined
AuthzPermissionException - if current user lacks permission
AuthzRealmLockException - if group has a lock preventing changes

joinGroup (With Size Limit)

void joinGroup(String authzGroupId, String role, int maxSize)
    throws GroupNotDefinedException, AuthzPermissionException, 
           GroupFullException, AuthzRealmLockException

Join a group only if it won’t exceed the maximum size.

maxSize

int

required

Maximum permitted size of the AuthzGroup

Throws:

GroupFullException - if adding the user would exceed maxSize

unjoinGroup

void unjoinGroup(String authzGroupId)
    throws GroupNotDefinedException, AuthzPermissionException, AuthzRealmLockException

Cause the current user to unjoin an AuthzGroup.

authzGroupId

String

required

The AuthzGroup ID

Provider Integration

getProviderIDsForRealms

Map<String, List<String>> getProviderIDsForRealms(List<String> realmIDs)

Get all provider IDs for the given realms.

realmIDs

List<String>

required

List of realm IDs

Map<String, List<String>>

Map where key is realm ID and value is list of provider IDs

getAuthzGroupIds

Set<String> getAuthzGroupIds(String providerId)

Get AuthzGroup IDs with the given provider ID.

providerId

String

required

The provider ID

Set<String>

Set of AuthzGroup IDs (e.g., “/site/1234”, “/site/1234/group/5678”)

getProviderIds

Set<String> getProviderIds(String authzGroupId)

Get provider IDs associated with an AuthzGroup.

authzGroupId

String

required

The AuthzGroup ID

Set<String>

Set of external group IDs (non-compound IDs)

Utility Methods

authzGroupReference

String authzGroupReference(String id)

Get the internal reference for accessing an AuthzGroup.

String

required

The AuthzGroup ID

String

The internal reference

refreshUser

void refreshUser(String userId)

Refresh a user’s AuthzGroup external definitions (from providers).

userId

String

required

The user ID

getRoleName

String getRoleName(String roleId)

Get a display name for a role.

roleId

String

required

The role ID (e.g., “.auth”, “Instructor”)

String

Display name for the role

getMaintainRoles

Set<String> getMaintainRoles()

Get all maintain roles.

Set<String>

Set of role IDs with maintain permissions

Permission Check Methods

allowUpdate

boolean allowUpdate(String id)

Check if current user is allowed to update an AuthzGroup.

String

required

The AuthzGroup ID

boolean

true if allowed, false otherwise

allowAdd

boolean allowAdd(String id)

Check if current user is allowed to add an AuthzGroup.

allowRemove

boolean allowRemove(String id)

Check if current user is allowed to remove an AuthzGroup.

allowJoinGroup

boolean allowJoinGroup(String id)

Check if current user is allowed to join a group.

allowUnjoinGroup

boolean allowUnjoinGroup(String id)

Check if current user is allowed to unjoin a group.

AuthzGroup Object

The AuthzGroup interface provides access to realm information:

AuthzGroup realm = authzGroupService.getAuthzGroup("/site/biology-101");

// Identity
String id = realm.getId();
String reference = realm.getReference();
String providerGroupId = realm.getProviderGroupId();

// Members
Set<Member> members = realm.getMembers();
Member member = realm.getMember(userId);
Set<String> users = realm.getUsers();
boolean hasRole = realm.hasRole(userId, roleId);
int userCount = realm.getUsersHasRole(roleId).size();

// Roles
Set<Role> roles = realm.getRoles();
Role role = realm.getRole(roleId);
Role userRole = realm.getUserRole(userId);

// Functions/Permissions
boolean allowed = realm.isAllowed(userId, function);
Set<String> allowedFunctions = realm.getAllowedFunctions(function, roleSets);

Common Use Cases

Checking User Permissions

// Check if current user can update a site
String userId = sessionManager.getCurrentSessionUserId();
String siteRef = "/site/" + siteId;

if (authzGroupService.isAllowed(userId, "site.upd", siteRef)) {
    // User can update site
}

// Check group-specific permission
String groupRef = "/site/" + siteId + "/group/" + groupId;
if (authzGroupService.isAllowed(userId, "content.read", groupRef)) {
    // User can read group content
}

Getting All Users with a Permission

// Get all users who can grade assignments in a site
Set<String> graders = authzGroupService.getUsersIsAllowed(
    "assignment.grade",
    Collections.singleton("/site/biology-101")
);

// Load user details
List<User> graderUsers = userDirectoryService.getUsers(graders);

Managing Site Membership

// Add a user to a site with a role
AuthzGroup siteRealm = authzGroupService.getAuthzGroup("/site/biology-101");
siteRealm.addMember(userId, "Student", true, false);
authzGroupService.save(siteRealm);

// Change a user's role
siteRealm.removeMember(userId);
siteRealm.addMember(userId, "Teaching Assistant", true, false);
authzGroupService.save(siteRealm);

// Remove a user from a site
siteRealm.removeMember(userId);
authzGroupService.save(siteRealm);

Overview

Kernel Services

Tool APIs

REST API

​Overview

​Key Concepts

​Constants

​Security Functions

​Core Methods

​AuthzGroup Access

​getAuthzGroup

​getAuthzGroups

​countAuthzGroups

​AuthzGroup Creation

​addAuthzGroup

​addAuthzGroup (Copy)

​newAuthzGroup

​AuthzGroup Modification

​save

​AuthzGroup Removal

​removeAuthzGroup

​removeAuthzGroup (by ID)

​Permission Checking

​isAllowed (Single Group)

​isAllowed (Multiple Groups)

​User and Role Queries

​getUsersIsAllowed

​getUsersIsAllowedByGroup

​getUserCountIsAllowed

​getAuthzGroupsIsAllowed

​getUserRole

​getUserRoles

​getUsersRole

​getAllowedFunctions

​Membership Management

​joinGroup

​joinGroup (With Size Limit)

​unjoinGroup

​Provider Integration

​getProviderIDsForRealms

​getAuthzGroupIds

​getProviderIds

​Utility Methods

​authzGroupReference

​refreshUser

​getRoleName

​getMaintainRoles

​Permission Check Methods

​allowUpdate

​allowAdd

​allowRemove

​allowJoinGroup

​allowUnjoinGroup

​AuthzGroup Object

​Common Use Cases

​Checking User Permissions

​Getting All Users with a Permission

​Managing Site Membership

​See Also

Build docs developers (and LLMs) love

Overview

Key Concepts

Constants

Security Functions

Core Methods

AuthzGroup Access

getAuthzGroup

getAuthzGroups

countAuthzGroups

AuthzGroup Creation

addAuthzGroup

addAuthzGroup (Copy)

newAuthzGroup

AuthzGroup Modification

save

AuthzGroup Removal

removeAuthzGroup

removeAuthzGroup (by ID)

Permission Checking

isAllowed (Single Group)

isAllowed (Multiple Groups)

User and Role Queries

getUsersIsAllowed

getUsersIsAllowedByGroup

getUserCountIsAllowed

getAuthzGroupsIsAllowed

getUserRole

getUserRoles

getUsersRole

getAllowedFunctions

Membership Management

joinGroup

joinGroup (With Size Limit)

unjoinGroup

Provider Integration

getProviderIDsForRealms

getAuthzGroupIds

getProviderIds

Utility Methods

authzGroupReference

refreshUser

getRoleName

getMaintainRoles

Permission Check Methods

allowUpdate

allowAdd

allowRemove

allowJoinGroup

allowUnjoinGroup

AuthzGroup Object

Common Use Cases

Checking User Permissions

Getting All Users with a Permission

Managing Site Membership

See Also