Identity Access Management (IAM)

Identity Access Management (IAM) provides fine-grained access control over the services running in Alpaca Infrastructure Platform. We present three models - User, Group, and Membership.

Definitions

A user represents a person using AIP. A group represents a collection of users who share certain resources with common privileges. Membership represents the status of a user being associated with a group.

Case study

Let's say we have Alice and Bob (users). They are members of Administrators (a group). Alice is the owner of the group, Administrators (a membership with role owner). Bob is a member of Administrators (a membership with role member). We can describe this case with the following objects.

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

Above objects can be created by following actions. We assume Alice already exists.

• Alice creates user Bob.
• Alice creates group Administrators.
• Alice becomes an owner of Administrators. (This happens automatically without an action.)
• Alice invites Bob as a member of Administrators.

The actions are mapped to the following API requests.

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

User management

User privileges

Alpacon users have three privilege levels.

General users

Users have full access to the system except for the things require privilege. Followings are the example of what users can do.

• Update his/her profile.
• Update or delete an owned group.
• Access servers with permission.

Staff users

Staff users can do the following actions in addition to general users.

• Add, update, or delete a user.
• Add a group.

Superusers

Superusers have all privileges on the system including the followings.

• Manage a user's staff and superuser status.

Listing users

You can list the registered users.

Request:

GET /api/iam/users/

Adding a user

Staff users or above can add a new user. You cannot assign higher privilege than yours to a new user.

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. +82-10-1234-5678)
• 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

• 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, ...

How can we know all blacklist????

Retrieving, updating, or deleting a user

A user object can be fetched or updated with 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 changed by a staff or a superuser. This does not require confirmation of previous password.

If <id> is -, the login user object will be returned.

Please note that the password field can only be updated by an admin user. For more about changing password, please refer to Authentication.

Please note that there should be at least a superuser in the system. When you try to remove last superuser, we will throw a validation error.

Group management

Listing groups

You can list groups that you are associated with or you can ask to join.

Request:

GET /api/iam/groups/

Adding a group

Staff users or above can add a new group to alpacon. When you create a group, you become an owner of the group automatically.

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

A group object can be fetched or updated with 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 associate all users with this group by default. When we are creating user accounts on servers, we use this group. As this is a required group in the system, users cannot remove this group or change memberships.

Membership management

Membership states the role of a user in a group. There are three membership roles, owner, manager, and member.

• Member
  • Access all resources granted to the group.
• Manager
  • Invite a user to the group as a member.
  • Remove a member from the group.
  • Update group information.
• Owner
  • Invite a user to the group as a manager or an owner.
  • Remove a manager or an owner from the group.
  • Delete the group.

Listing memberships

You can list membership status of a group or a user with the following API.

Request:

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

If you want to list the membership status of a group, you can use group filter.

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

When listing membership status of a user, you can use user filter.

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

It is also possible to combine both filters. In this case, a specific membership for a user in a group will be returned.

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 with the following API. To do this, you should be a manager or an owner of the group.

Request:

POST /api/iam/memberships/

Request data:

• group: UUID of a group
• user: UUID of a user
• role: Role of the user. Choices are owner, manager, and member. owner and manager roles can only be assigned by a group owner.

Retrieving or updating a membership

Each membership object has unique UUID. A membership object can be fetched or updated with the following API.

• URL: /api/iam/memberships/<id>/
• HTTP methods: GET, PUT, PATCH
• Notes
  • Only role can be changed.
  • PUT and PATCH are only available for group owners as they do privilege escalation or degradation (e.g., member → manager or owner → member).
  • If only one owner is left, the role cannot be changed. Alpacon will return 400 Bad Request with proper error messages.

Deleting a membership

Individual membership can be deleted using the following API.

Request:

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

Notes:

• Each member can delete his/her membership, meaning that users can leave a group if they want.
• A manager can delete a member from a group.
• An owner can delete a member, manager, or owner from a group.
• If only one owner is left, it cannot be deleted. Alpacon will return 400 Bad Request with proper error messages.
• Memberships for default group alpacon cannot be changed.