Identity Access Management (IAM)

Identity Access Management (IAM) provides fine-grained access control over services running in the Alpacon. IAM is composed of three models—User, Group, and Membership.

Definitions

• A user represents a individual using Alpacon.
• A group is a collection of users who share access to certain resources with common privileges.
• A membership defines the relationship between a user and a group, including the user's role within that group.

Case study

Let's say we have two users: Alice and Bob. They are both members of a group named Administrators. Alice is the owner of the group, Administrators (Membership role: owner). Bob is a member of Administrators (Membership role: member). We can represent this scenario with the following objects.

• User (Alice)
• User (Bob)
• Group (Administrators)
• Membership (Alice, Administrators, owner)
• Membership (Bob, Administrators, member)

The following actions are required to set up this scenario. We assume Alice already exists.

• Alice creates a user: Bob.
• Alice creates a group: Administrators.
• Alice is automatically assigned as the owner of the Administrators group.
• Alice invites Bob to join the group as a member.

These actions correspond to the following API requests.

• POST /api/iam/users/: Create user Bob
• POST /api/iam/groups/: Create group Administrators
• POST /api/iam/memberships/: Create a membership (user, group, role) = (bob, administrators, member)

User management

User privileges

Alpacon defines three levels of user privileges.

General users

General users have full access to the system, except operations that require elevated privileges. Examples of actions they can perform include.

• Updating their own profile.
• Updating or deleting groups they own.
• Accessing servers they have permission for.

Staff users

In addition to the capabilities of general users, staff users can:

• Add, update, or delete users.
• Add new groups

Superusers

Superusers have all available privileges on the system, including the following:

• Manage other user's staff or superuser status

Listing users

You can retrieve a list of all registered users.

Request:

GET /api/iam/users/

Adding a user

Staff users and superusers can create a new user. You cannot assign a higher privilege level to a new user than the one you currently hold.

Request:

POST /api/iam/users/

Request data:

• username: Username to login
• password: Password to login
• first_name: First name
• last_name: Last name
• email: Email address
• phone: Phone number (e.g., +1 (650) 555-1234)
• tags, description: Additional information to identify the user
• shell: System shell (/bin/bash by default)
• is_active: Active users are allowed to login.
• is_staff: Staff users are admin members. They can manage members.
• is_superuser: Superuser have all privileges on the system.

Blacklist for usernames—The following usernames are reserved and cannot be used:

• root, sudo, su, admin, adm
• daemon, bin, sys, sync, games, man, lp, mail, news, uucp, proxy, www-data backup, list, irc, gnats, nobody, systemd-*, syslog, _apt, lxd, messagebus, uuidd, dnsmasq, sshd, mysql, ...

Retrieving, updating, or deleting a user

You can retrieve or modify a user object using the following API:

• URL: /api/iam/users/<id>/
• HTTP methods: GET, PUT, PATCH, DELETE
• username, uid, and home_directory cannot be changed.
• password can be be updated by a staff user or a superuser without requiring the current password.

If <id> is -, the logged-in user's object will be returned.

Please note that the password field can only be updated by an admin. For password change instructions, see Authentication.

There must always be at least one superuser in the system. Attempting to remove the last superuser will result in a validation error.

Group management

Listing groups

You can retrieve a list of groups you are currently a member of or groups you can request to join.

Request:

GET /api/iam/groups/

Adding a group

Staff users or higher can create new groups in Alpacon. When a group is created, the creator automatically becomes its owner.

Request:

POST /api/iam/groups/

Request data:

• name: Group name
• display_name: Group name for display
• tags, description: Additional information to identify the group
• gid: System group information

Retrieving, updating, or deleting a group

You can retrieve, update, or delete a group using the following API.

• URL: /api/iam/groups/<id>/
• HTTP methods: GET, PUT, PATCH, DELETE
• name and gid cannot be changed.

System group

We have a group named alpacon, and all users are automatically assigned to it by default. When creating user accounts on servers, this group is used to ensure default access. As a required system group, it cannot be removed or modified by users.

Membership management

Membership defines a user's role within a group. There are three membership roles, owner, manager, and member.

• Member
  • Access all resources granted to the group.
• Manager
  • Invite users to the group as members.
  • Remove members from the group.
  • Update group information.
• Owner
  • Invite users to the group as managers or owners.
  • Remove managers or owners from the group.
  • Delete the group.

Listing memberships

You can retrieve the membership status of a group or user using the API below.

Request:

GET /api/iam/memberships/?group=&user=

To list the memberships of a specific group, use the group filter.

GET /api/iam/memberships/?group=41645970-e8cd-4f42-9047-21202928ba3f

To list the memberships of a specific user, use the user filter.

GET /api/iam/memberships/?user=93ccd786-92b5-4a09-8807-6ff21d26e5fb

You can also combine both filters to retrieve a specific membership record:

GET /api/iam/memberships/?group=41645970-e8cd-4f42-9047-21202928ba3f&user=93ccd786-92b5-4a09-8807-6ff21d26e5fb

Adding a membership

You can assign a user to a group using the API below. To do so, you must be a manager or an owner of the group.

Request:

POST /api/iam/memberships/

Request data:

• group: UUID of the group
• user: UUID of the user
• role: User's role in the group. Valid roles are owner, manager, and member. Only a group owner can assign the owner and manager roles.

Retrieving or updating a membership

Each membership object has a unique UUID. You can retrieve or update a membership with the following API.

• URL: /api/iam/memberships/<id>/
• HTTP methods: GET, PUT, PATCH
• Notes
  • Only the role field is updatable.
  • PUT and PATCH are available for group owners only, as they can promote or demote roles (e.g., member → manager or owner → member).
  • If there is only one owner left in the group, the role cannot be changed. Alpacon will return 400 Bad Request with an appropriate error message.

Deleting a membership

You can delete a membership with the following API.

Request:

DELETE /api/iam/memberships/<id>/

Notes:

• Any member can delete their own membership (i.e., leave a group).
• A manager can remove a member from the group.
• An owner can remove a member, manager, or even another owner from the group.
• If only one owner is left, they cannot be deleted. Alpacon will return 400 Bad Request with an appropriate error messages.
• Memberships for the default group alpacon cannot be modified.