Group-based role assignment

Manually assigning roles to users in your application can consume significant time for administrators. This becomes especially challenging in large enterprises where access requirements change frequently. Scalekit automates this process by enabling administrators to create workflows that automatically update your app with the correct user roles.

How group-based role assignment works

Organization administrators commonly manage varying access levels by grouping users based on their specific access requirements. For example, if you develop an application similar to GitHub with roles like maintainer, writer, and viewer, customer administrators can create user groups for each role within their directory provider.

Scalekit notifies your application when administrators create groups or add users to groups. This enables you to take necessary actions such as creating or modifying user roles as directed by the organization’s administrator.

Scalekit delivers normalized information regardless of which directory provider your customers use. This eliminates the need for you to transform data across different providers. Users can belong to multiple groups and may receive multiple roles in your application, depending on your role-mapping logic.

Set up automatic role assignment

To enable administrators to map groups to roles in your app, complete these steps:

1. Go to the Scalekit dashboard
2. Select “SCIM Provisioning”
3. Switch to the “Role assignment” tab
4. Register your app’s roles

The first role you create becomes the default role automatically. Users who don’t belong to any specific group receive this role when you create their accounts. To change the default role, navigate to the role settings, click the ”…” menu next to your preferred role, select “Edit,” and toggle the “Set as default role” option.

Choose clear display names and descriptions for your roles. This helps customers understand and align with the access levels in the admin portal.

Connect organization groups to app roles

After you create the roles, they reflect the roles in your app. Users receive role assignments based on the groups they belong to.

You can set up this mapping in two ways:

1. Set up mapping in the Scalekit dashboard on behalf of organization administrators. Select the ‘Organization’ and go to ‘SCIM Provisioning’ tab.
2. Share the admin portal link with organization administrators so they can set up the mapping themselves

Scalekit automatically displays mapping options in both the Scalekit dashboard and the admin portal. This allows administrators to connect organization groups to app roles.

Handle role update events

Scalekit continuously monitors updates from your customers’ directory providers and sends event payloads to your application through a registered webhook endpoint. To set up these endpoints and manage subscriptions, note the ‘Webhooks’ option in the Scalekit dashboard.

Listen for the organization.directory.user_updated event to determine a user’s role from the payload. Scalekit automatically includes a role property relevant to your app, based on the role information you configured in the Scalekit dashboard.

Node.js

Create a webhook endpoint for role updates

// Webhook endpoint
app.post('/webhook', async (req, res) => {
  // Extract event data
  const event = req.body;
  const { email, name, roles } = event.data;
  console.log('Admin added user to Viewer Group -> Scalekit informs Your App\n');

  // Destructure role_name from roles array
  const roleName = roles.length > 0 ? roles[0].role_name : null;
  console.log('Role name received:', roleName);

  // Logic to update user role and permissions
  await assignRole(roleName, email);
  console.log('App updated access for user:', email);

  res.status(201).json({
    message: 'Role assigned',
  });
});

Python

Create a webhook endpoint for role updates

from fastapi import FastAPI, Request

app = FastAPI()

@app.post("/webhook")
async def api_webhook(request: Request):
    # Parse request body
    body = await request.body()
    payload = json.loads(body.decode())

    # Extract user data
    user_roles = payload['data']['roles']
    user_email = payload['data']['email']

    print("User Roles:", str(roles))
    print("User email:", str(email))

    # Business logic to assign role
    await assign_role(roles[0], email)

    return JSONResponse(
        status_code=201,
        content=''
    )

Java

Create a webhook endpoint for role updates

@PostMapping("/webhook")
public String webhook(@RequestBody String body, @RequestHeader Map<String, String> headers) {
  ObjectMapper mapper = new ObjectMapper();

  try {
    JsonNode node = mapper.readTree(body);
    JsonNode roles = node.get("data").get("roles");
    String email = node.get("data").get("email").asText();

    System.out.println(roles);
    System.out.println(email);
    // Add role to user

  } catch (IOException e) {
    return "error";
  }

  return "ok";
}

Go

Create a webhook endpoint for role updates

mux.HandleFunc("POST /webhook", func(w http.ResponseWriter, r *http.Request) {
    // Read request body
    bodyBytes, err := io.ReadAll(r.Body)
    if err != nil {
        http.Error(w, err.Error(), http.StatusBadRequest)
        return
    }

    // Parse webhook payload
    var body struct {
        Data map[string]interface{} `json:"data"`
    }

    err = json.Unmarshal(bodyBytes, &body)
    if err != nil {
        http.Error(w, err.Error(), http.StatusBadRequest)
        return
    }

    // Extract user data
    roles := body.Data["roles"]
    email := body.Data["email"]

    fmt.Println("Roles: ", roles)
    fmt.Println("Email: ", email)

    w.WriteHeader(http.StatusOK)
})

Refer to all the directory webhooks you can subscribe.