Guide for VO Admins#

This guide is for the person who knows who is on the team. It explains how to turn that knowledge into a group structure services can act on.

If you have not read the concept page, read it first - it covers the difference between a group and an allocation, and why “VO” and “Community” mean the same thing.

Is this you?#

You are a VO admin if you can authoritatively answer “who is on this team, and which part of it are they in?” - principal investigators, work-package leads, group leaders, data stewards, task-force coordinators. Anything from a three-person working group to a multiple-hundred-person distributed project.

What you are actually being asked to do#

1. Identify the members of your project.
2. Structure them into subgroups, where a distinction matters.
3. Keep it current as people join, move and leave.

Equally important is what is not your job: deciding what a service grants (you ask, the provider decides), operating the AAI, or managing accounts - users bring their own institutional identities, and you never create, reset or delete anybody’s.

Design first, click later#

Groups are cheap to create and expensive to rename, because their names end up in service configurations you do not control. Spend half an hour with a pen first.

The question to ask about every group you are tempted to create is not “does this reflect how the project is organised?” but:

Does some service treat these people differently from the rest of the team - today, or plausibly soon?

If not, you have invented documentation rather than authorisation. Put it in the project wiki instead.

Designing the group tree#

Groups form a tree: each has one parent, and the top is your VO.

A worked example for a fictional project, cakemaster:

cakemaster                     the whole project - everyone
├── admins                     the handful of people who run things
├── researchers                Anybody accessing research services
└── data
    ├── curators               may modify the reference dataset
    └── consumers              may read it

Every group here earns its place. cakemaster is the unit you apply for resources with, and the natural answer to “is this person on the project at all?”. data:curators and data:consumers exist because the repository genuinely distinguishes them. admins exists because some services need to know who to trust with destructive operations.

Two or three levels is almost always enough; if you are at level five you are modelling the org chart again. Breadth is fine - fifteen sibling work-package groups are easy to reason about - but depth is a smell.

Common patterns, and when to reach for them:

Subgroup or role?#

• Use a subgroup for a different set of people doing a different job.
• Use a role for the same set of people, where some hold a particular standing - role=manager, role=chair, role=operator.

If setting this up would mean listing the same person in two groups, you wanted a role.

Two specified behaviours that surprise people:

1. Holding a role implies membership. Someone with cakemaster:data:role=manager is already a member of cakemaster:data and cakemaster; do not add them again as a plain member.
2. Roles do not inherit upwards. Being a manager of cakemaster:data does not make you a manager of cakemaster.

That second point is a feature: it lets you appoint a work-package manager without handing them the whole project.

Naming: what you choose, you keep#

Group names do not stay inside the Community AAI. They are concatenated into entitlement strings that land in service configuration files, log lines, regular expressions, and sometimes POSIX group names on a login node. The name is an interface.

You choose only the tail end:

urn:geant:dfn.de:nfdi.de:nfdi4cake:group:cakemaster:data:curators:role=manager#aai.example.de
└────────── namespace ───────────┘ └lit┘ └─ grp ──┘ └ subgroups ┘ └── role ──┘ └ authority ─┘
└───── chosen by the AAI operator ──────┘└────────────── yours ──────────────┘ └ technical ─┘

• Lowercase, ASCII, no spaces. Spaces are legal but must be percent-encoded (%20), making every config file uglier and every regular expression more fragile. Non-ASCII is worse.
• Use - or _ between words, consistently.
• Name what it is, not who runs it. wp3 stays correct when Anne moves on; annes-group does not.
• Name the purpose, not the software. collaborationtool, not nextcloud. When the software behind it is replaced, the group, the entitlement and every configuration that matches it stay as they are.
• Keep it short. These strings get concatenated, logged and truncated.
• Avoid names that are prefixes of each other. cakemaster and cakemaster-extended look fine until a sloppy match grants one to the other.

The namespace itself is registered; the NFDI registry lives at https://www.nfdi.de/persistent-identifiers. Your consortium’s AAI contact will tell you your namespace.

This is the same example taken apart in full - roles, the authority suffix and all - in the service admin guide, if you want to see what your service administrators will be matching on.

The membership lifecycle#

Getting people in. Either self-request with your approval (publish an enrolment link; this scales, and puts data entry on the person who knows their own details) or invitation by email address (better for small, known teams). Most Community AAIs support both.

Either way the new member accepts the VO Acceptable Use Policy. This is not a formality: it is what makes the policy chain hold together, and what providers rely on when accepting members they do not know. Adapt the VO-AUP template rather than writing your own - english ( ), german ( ).

Getting people out. Remove departing members promptly, with one caveat.

Most systems also offer suspension: access stops, membership history is retained. Usually the right tool during an investigation.

If you suspect a security incident#

A compromised account, credentials posted somewhere they should not be, a member behaving in a way that suggests their machine is not theirs any more - none of this is something you are expected to handle by yourself.

The formal process is the Security Incident Response Procedure (SIRP), one of the NFDI policies you signed up to. Practically, it asks you to:

1. Suspend first. Suspend the affected membership and preserve what you have - logs, mails, anything that shows what happened. Do not tidy up.
2. Follow your own institution’s procedure as well; the SIRP sits alongside it, not instead of it.
3. Report within one working day to the security contact above.
4. Stay reachable. Incidents cross organisational boundaries, and responses to queries are expected within short notice.

DFN documents the federation-level procedure, including the reporting template, at doku.tid.dfn.de/de:aai:incidentresponse. The underlying trust framework is Sirtfi, which is what lets security teams at different institutions work together on the same incident.

Delegating the work#

If your team or community extends to more than about twenty people, delegate. Appoint a manager per subgroup to approve their own joiners and expire their own leavers; you keep the top level. This is the same delegation principle that got membership out of the service administrators’ hands, applied one level down.

Policies you have to satisfy#

These exist so providers can accept your members without assessing your project individually.

Policies you must follow:

• VO Membership Management Policy (VOMMP) - what you commit to: accurate membership, handling departures, incident response.
• VO Lifecycle Policy (VOLP) - creation, handover, dormancy, termination. Pay attention to deprovisioning; it is the part everyone forgets.
• Security Incident Response Procedure (SIRP) - what happens when something goes wrong. See above; the short version is that you suspend and report, and the security team takes it from there.
• Top Level Policy - the frame the rest hangs off, and short.

Templates you adapt:

• VO Acceptable Use Policy (VO-AUP) - what your members agree to when they join. english ( ), german ( )
• Privacy Policy Template - for generating your VO Privacy Policy. english ( ), german ( )

The full set, including the policies that apply to other roles, is on the policies and templates page; the VO Administrator page collects the VO-specific ones.

What the four NFDI Community AAIs give you#

NFDI offers AcademicID, didmos, RegApp and Unity. Each consortium settles on one, so you will not be choosing - see the consortium overview for which is which.

All four do what this guide describes: hierarchical VOs and subgroups, roles, membership management, and AARC-G069 entitlements. A structure designed as above works on any of them, and survives a migration.

They differ in the details that shape your daily experience - self-service interface, automation, external data sources, expiry handling, bulk APIs - and those move as the products develop. See the feature matrix rather than a snapshot here that would go stale.

When groups are not enough: resource capabilities#

Sooner or later a provider says “we can’t do group-based access, but we can switch on a permission per user”. That is a resource capability (see the concept page).

In one line: a group says “this person is on the cakemaster team”; a capability says “this person may read dataset 42”. The first is a fact the service interprets, the second a decision already taken.

You do not normally mint capabilities yourself - the AAI or infrastructure operator issues them under a configured rule. Some Community AAIs let a VO admin drive that rule; ask yours.

Three reasons to keep preferring groups:

• Groups travel; capabilities do not. Change provider and your group comes with you, while the capabilities are worthless.
• Capabilities are arranged per resource, so effort grows with the number of resources instead of staying flat.
• Capabilities hide decisions you did not take. When someone unexpectedly loses access, the answer is no longer in your own membership list.

One case where capabilities are clearly right: per-object access at a granularity that would explode your group tree. The tell-tale is noticing you are about to create dataset-42-readers, dataset-43-readers, and so on. Stop, and ask the provider about capabilities.

Talking to service providers#

What to give them:

• The exact entitlement string, copied from the Community AAI, not retyped from memory.
• What the group means, one sentence each. “Everyone on the project” and “the four people who may modify the reference dataset” are very different risk propositions.
• A contact that outlives any individual.
• Expected size and growth, so they can size things.
• Your renewal cadence, so they know how stale membership can get.

What to ask in return: which string did you match, exactly? What does it grant? And what happens when I remove someone - which establishes what you can rely on, given the caveat above.

Checklist#

Before you create anything

• [ ] Sketched the structure on paper
• [ ] Every group justified by a real access distinction
• [ ] Decided subgroup vs role for each distinction
• [ ] Names are lowercase, ASCII, descriptive, not personal
• [ ] Depth is two or three levels, not five

Setting up

• [ ] VO created in the consortium’s Community AAI
• [ ] AUP in place and shown at enrolment
• [ ] Enrolment route decided - self-request or invitation
• [ ] Membership expiry configured
• [ ] Subgroup managers appointed
• [ ] A second top-level admin exists

Running it

• [ ] Annual re-confirmation of every member, in the calendar / delegated to CAAI
• [ ] Departures actioned promptly
• [ ] Security contact security@aai.dfn.de noted somewhere you will find it in a hurry
• [ ] Entitlement strings documented for the services that use them
• [ ] Structure reviewed when the project’s resource needs change

See also#

• The VO Concept - the model, and the benefits argument
• Guide for Service Admins - worth skimming to see what you are handing people
• VO Administrator: policies & templates
• Community AAI Software and the Feature Matrix

Last change: Oct 15, 2026 12:30:32