Milesoft IAM Extension (`iam-ext`)

1. Overview & Purpose

The IAM Extension (iam-ext) is a unified, highly optimized, and robust developer utility designed to provide a secure and standardized facade around Google Cloud Identity and Access Management (IAM). It simplifies programmatic IAM policy manipulation within the Milesoft ecosystem by offering a simple API to grant and revoke roles for various members on GCP projects, shielding downstream developers from raw Google Cloud API boilerplate.

Key Benefits & Core Capabilities:

Standardized Facade: Provides a clean, type-safe API for managing IAM policy bindings, avoiding complex and repetitive GCP Resource Manager and IAM client calls.
Support for Both Granting & Revoking: Fully supports both granting and revoking role bindings with matching, flexible method signatures.
Automatic Binding Cleanup: When a role's member is removed, if that binding's member list becomes completely empty, the binding itself is safely cleaned up from the policy to keep IAM configurations clean and valid.
Standardized Member Models: Integrates natively with standard, strongly-typed Member record models (spanning Users, Groups, Service Accounts, and Domains).

2. Installation & Dependency Configuration

The IAM Extension is hosted securely inside our Google Cloud Artifact Registry repository.

To configure your application to resolve and pull this dependency:

2.1 Gradle Setup (`build.gradle`)

Apply the Google Cloud Artifact Registry plugin and configure the Maven repository block:

plugins {
    id "com.google.cloud.artifactregistry.gradle-plugin" version "2.2.5"
    id "java"
}

repositories {
    mavenLocal()
    mavenCentral()
    maven {
        url "artifactregistry://us-west2-maven.pkg.dev/milesoft-repo/repo-maven"
    }
}

dependencies {
    // Milesoft Commons foundation (required by iam-ext)
    implementation "io.milesoft:commons:2.0.1"
    
    // IAM Integration Extension
    implementation "io.milesoft:iam-ext:1.0.0"
}

3. Configuring IAM in Spring Boot

Downstream Spring Boot microservices and applications utilize a standard configuration pattern to initialize and inject the IamService as a Spring-managed bean.

3.1 Define Application Properties

Configure your target GCP project ID in your properties configuration (e.g., application.yml or application.properties):

iam:
  project: "your-gcp-project"

3.2 Injecting IAM Configuration

To enable the IamService bean inside your application context, declare it inside a Spring configuration class:

import io.milesoft.iam.services.IamService;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class IamConfig {

    @Bean
    public IamService iamService(@Value("${iam.project}") String project) {
        return new IamService(project);
    }
}

4. Key Components

The library exposes several key types for direct runtime usage or custom configurations.

4.1 `IamService`

The main Orchestrator service. It reads, modifies, and writes IAM policies by communicating with Google Cloud's Resource Manager API using GCP standard client abstractions.

4.2 `Member` Record

A record representing a standard IAM policy member:

public record Member(MemberType type, String email) {
    public Member {
        checkNotNull(type, "type must not be null");
        checkArgument(StringUtils.isNotBlank(email), "email must not be blank");
    }
}

4.3 `MemberType` Enum

Specifies standard member categories including:

User (prefixed with user:)
Group (prefixed with group:)
ServiceAccount (prefixed with serviceAccount:)
Domain (prefixed with domain:)

5. API Reference Guide

5.1 `IamService`

A high-performance orchestration service that handles IAM role granting and revoking on a project level.

Constructor:

public IamService(String project)

project: The GCP Project ID to manage. Must not be blank.

Core Methods:

Method Signature	Return Type	Description
`grantRole(String role, Member member, Member... additional)`	`void`	Grants the specified IAM role to one or more members.
`grantRole(String role, Collection<Member> members)`	`void`	Grants the specified IAM role to a collection of members. Creates a new binding if it does not already exist, or appends the members to the existing binding.
`revokeRole(String role, Member member, Member... additional)`	`void`	Revokes the specified IAM role from one or more members.
`revokeRole(String role, Collection<Member> members)`	`void`	Revokes the specified IAM role from a collection of members. Filters out the specified members. If no members are left under that role binding, the binding is completely removed from the policy.

6. Practical Real-World Code Examples

These integration examples represent standard, battle-tested patterns for IAM policy manipulation across the Milesoft codebase.

Example A: Granting and Revoking Roles in Service Logic

This example shows how to load your IamService bean and dynamically manage access permissions on your GCP project.

import static com.google.common.base.Preconditions.checkNotNull;

import io.milesoft.iam.domain.Member;
import io.milesoft.iam.enums.MemberType;
import io.milesoft.iam.services.IamService;
import org.springframework.stereotype.Service;

@Service
public class AccessControlService {

    private final IamService iamService;

    @Autowired
    public AccessControlService(IamService iamService) {
        this.iamService = checkNotNull(iamService, "iamService must not be null");
    }

    public void onboardDeveloper(String email) {
        final Member developer = new Member(MemberType.User, email);
        
        // Grant roles
        iamService.grantRole("roles/viewer", developer);
    }

    public void offboardDeveloper(String email) {
        final Member developer = new Member(MemberType.User, email);
        
        // Revoke roles
        iamService.revokeRole("roles/viewer", developer);
    }
}

Milesoft IAM Extension (iam-ext)