Skip to content

ezSign - Groups

A group in ezSign answers one question: who may sign, and with which keys?

You do not add people to a group one by one. Your single sign-on already knows which teams someone belongs to, and it puts those team names into the token it hands ezSign when they sign in. On the Groups page you say which of those names means which group - the people whose token says finance are the Finance group - and then tick the key profiles that group is allowed to sign with.

From then on it takes care of itself. Someone joins Finance in your directory, signs in to ezSign, and the Finance key profiles are simply there.

Who does this

This is an administrator task. Operators - the people who sign documents - never see this page; they only notice the result, which is what they are offered when they come to sign.

Before you start

You need two things.

The exact group values your single sign-on sends. Not the pretty names shown in your directory's admin console - the values as they appear in the token. They are usually short and lower-case, like finance or hr-signers. Whoever runs your identity provider can tell you, or show you a decoded token. Spelling and capitals must match exactly.

At least one key profile, if you want the group to be able to sign straight away. A group with no key profile is created quite happily - it just cannot sign anything yet, and the page says so.

The claim name is already set

Which field in the token ezSign reads - the group claim name, usually groups - was chosen once during first-time setup, at the Group claim name box in step 2. This page is about the values inside that field, not the name of the field itself.

How membership works

flowchart LR
    User["An operator signs in"] --> Token["Their token carries<br/>group values, e.g. finance"]
    Token --> Match["ezSign finds the group<br/>those values are mapped to"]
    Match --> Profiles["They may sign with<br/>that group's key profiles"]

Figure: nobody is added to a group by hand. The token says which teams the person is in, and the Groups page says what each of those team names means in ezSign.

Membership is worked out at each sign-in, so a change you make here reaches people the next time they sign in. Nothing needs restarting.

Open the Groups page

In the administration area, open Manage → Groups in the left-hand menu.

The list shows one row per group:

Column What it shows
GROUP The name you gave the group.
OIDC CLAIMS The token values mapped to it, one chip each.
DESCRIPTION Your own note about what the group is for.
KEYPROFILES How many key profiles the group may sign with. Click the number to change them.
STATE Whether the group can sign - see Group states.
UPDATED The day the group was last changed. The list is ordered by it, so anything you have just created or edited is at the top.
ACTIONS The layers icon assigns key profiles, the pencil edits the group, and the ⋮ menu holds disable and delete.

Click any row to see the whole group on a read-only sheet - its values, its key profiles, its full description, and when it last changed. Looking is the default gesture; editing is the pencil, so nothing changes because you clicked to check something.

Group states

You never choose a group's state. ezSign works it out from the key profiles the group holds.

State What it means
PENDING The group exists and its values are mapped, but no key profile is assigned - so its members have nothing to sign with. Assign one and it becomes ACTIVE.
ACTIVE The group has at least one key profile. Its members can sign.
DISABLED You have deliberately taken the group out of service. Uploads and signing are refused for its members until you enable it again.

DISABLED outranks the other two. Editing a disabled group, or changing its key profiles, does not quietly put it back in service - only Enable group does. When you do enable it, it lands on ACTIVE or PENDING depending on whether it has a key profile at that moment.

Create a group

Press New group at the top right of the list and fill in the dialog.

Field Required? Description
Group name Required What you will call this group in ezSign - for example Finance. Up to 255 characters, and no two groups may share a name.
OIDC claim values Required The token values that mean this group. Type one and press Enter to turn it into a chip; add as many as you need, up to 32. Each may be up to 255 characters and may not contain spaces.
Description Optional A sentence for whoever reads this list next - Accounts payable, invoices only. Up to 255 characters.
Assign key profiles Optional Tick the key profiles this group may sign with. Leave them all unticked and the group is created as PENDING.

Several values, one group

A group can carry more than one value, and any single match puts a person in it. That is how you fold two directory teams into one ezSign group - map finance and accounting to the same group and either one admits its members.

Values are matched exactly

A value is compared to the token character for character, capitals included. Finance and finance are two different values, and mapping the wrong one admits nobody. This is why it is worth reading the value off a real token rather than off a directory screen. Spaces are rejected outright for the same reason - a token value never contains one, so it can only be a typo.

The same value cannot be mapped to two groups. If it were, someone carrying it would belong to both, and there would be no right answer to which keys they may sign with. The page tells you which group already has it.

Assign key profiles

A group's key profiles are the thing about it most likely to change, so there are three ways to the same dialog: the layers icon on the row, the number in the KEYPROFILES column, and the checklist inside the create and edit dialogs.

The checklist is the whole answer, not an addition. What is ticked when you save is what the group ends up with - ticking adds, unticking removes, and saving with nothing ticked removes them all and returns the group to PENDING.

Unassigning a profile never deletes it. It stays in your key profiles, available to any other group.

Edit a group

The pencil on the row opens the same fields you filled in when creating it.

Changing a value re-points membership

The claim values are what admit people. Change them and access moves: operators matched by the old value lose it, and those carrying the new one gain it - each at their next sign-in. Someone already signed in keeps what they had until then.

Renaming the group or editing its description changes nothing about who is in it. Those are for your benefit, not ezSign's.

Take a group out of service

Open the ⋮ menu on the row and choose Disable group, then confirm. Uploads and signing are refused for that group's members from the moment it lands - which is why it asks first.

Enable group in the same menu puts it back, with no confirmation, because it only undoes the block.

Disabling is the reversible answer to this group should stop signing for now. Nothing is lost: the values stay mapped, the key profiles stay assigned, and everything already signed is untouched.

Delete a group

Delete group in the ⋮ menu removes the group and its value mappings for good.

Two things stand in the way, deliberately.

Key profiles. A group holding key profiles is not deleted silently. The confirm dialog names the profiles it holds and tells you they will be kept - confirming unassigns them and then deletes the group. Your key profiles are never deleted with a group.

Signed documents. A group that has documents signed under it cannot be deleted at all. Those documents record which group they were signed for, and that record has to stay true. Disable the group instead.

Search the list

The search box asks the server, not just the rows on your screen - so it also finds a group a colleague created a minute ago, and it searches names, claim values and descriptions together.

What you type What you get
finance Groups matching that word.
"accounts payable" That exact phrase, in quotes.
payroll -temporary Matches for payroll, minus anything mentioning temporary.
fin* or *nance* A literal part-word match, for when you only remember a fragment.

Sorting a column, filtering, and paging through the list all work on whatever the search returned.

Troubleshooting

Another group already uses this name

Group names are unique, so the list can be read without ambiguity. Pick a different name - or, if the existing group is the one you actually meant, close the dialog and edit that one instead.

Group "…" already maps "…" - membership would be ambiguous

That token value is already mapped to the group named in the message. If it were mapped twice, someone carrying it would be in two groups with two sets of keys and no way to choose between them.

Decide which group should own the value: remove it from the other group first, then add it here. If both groups really do need the same people, the answer is usually one group with both values mapped to it, not the same value in two groups.

"…" cannot contain spaces - a token claim value carries none

You have typed a phrase where a token value belongs. Token values are single words like finance-signers. If you meant two values, add them as two separate chips; if the value really does contain a space, check it against a decoded token, because it almost certainly does not.

Use at most 32 claim values

A group named by more than a couple of dozen values is usually a pasted list rather than a team. Split it into more than one group, or ask your identity provider for a single value that covers the whole set.

Use at most 255 characters

The name, each claim value, and the description each hold up to 255 characters. Shorten the one the message is sitting under - the description is the usual culprit, and the detail sheet is a better home for the long version than the list is.

Group "…" still has key profiles assigned

You have asked to delete a group that can still sign. Delete it from the row's ⋮ menu rather than by another route: that confirm dialog lists the profiles, states that they are kept, and unassigns them for you as part of the delete. Nothing is removed from your key profiles either way.

Group "…" has signed document(s), so it cannot be deleted

Documents were signed under this group, and they record that. Deleting the group would leave that record pointing at nothing, so ezSign refuses. Disable group achieves what you are almost certainly after: no more signing for its members, with the history intact.

Someone signs in but is offered nothing to sign with

Work down this list:

  1. Is the group ACTIVE? A PENDING group has no key profile to offer, and a DISABLED one refuses signing outright.
  2. Do the values match the token exactly? Capitals count. Read the value off a decoded token rather than a directory screen.
  3. Have they signed in since your change? Membership is worked out at sign-in. Ask them to sign out and back in.
  4. Is the claim name right? If nobody at all is matched by any group, ezSign is probably reading the wrong field of the token. That is the Group claim name set in step 2 of first-time setup, not anything on this page.

FAQ

Why is my new group PENDING?

Because it has no key profile yet. A group with nothing to sign with is not usable, and PENDING says exactly that rather than pretending otherwise. Assign a key profile - from the layers icon on the row - and it becomes ACTIVE immediately. You never set the state by hand.

Can two groups share the same claim value?

No. Someone carrying that value would be in both groups with two different sets of keys, and there would be no correct answer to which they may sign with. Map the value to one group. If two teams genuinely need the same permissions, give one group both teams' values.

Does deleting a group delete its key profiles?

No, never. The delete confirm names the profiles the group holds and tells you they are kept - they are unassigned from the group and stay in your key profiles, ready for another group.

Do people have to sign out and back in after I change a group?

For anything that affects membership or keys, yes. Group membership and the profiles that follow from it are worked out when someone signs in, so a change reaches them at their next sign-in. Renaming a group or editing its description affects nobody's session.

Are claim values case-sensitive?

Yes. Finance and finance are two different values. Copy the value from a decoded token rather than retyping it from a directory console, where it is often shown with different capitals.

Can one group have more than one claim value?

Yes - up to 32 of them, and any single match admits a person. This is how two or three directory teams are folded into one ezSign group.

Should I disable a group or delete it?

Disable it, unless the group was a mistake. Disabling stops signing at once and is undone with one click, keeping the mappings and assignments you worked out. Deleting is permanent - and is refused outright once documents have been signed under the group.