Documentation Home

Principal URNs are a way of phrasing Globus Identities and Globus Groups as URNs.

The major improvement offered by the URN syntax is that it unambiguously associates a value with the correct type. That means that Group IDs are labeled as Groups, and Identity IDs are labeled as Identities.

What’s it look like?

Let’s jump in with some examples:

  • urn:globus:auth:identity:46bd0f56-e24f-11e5-a510-131bef46955c

  • urn:globus:groups:id:fdb38a24-03c1-11e3-86f7-12313809f035

That’s it!

Prefix Identity IDs with urn:globus:auth:identity: and Group IDs with urn:globus:groups:id:

Why URNs?

A big question is why it is not enough for us to use the IDs of Identities and Groups without this qualification. A few reasons which justify this choice:

  • Better for Humans. What is 46bd0f56-e24f-11e5-a510-131bef46955c? A Group, Identity, misplaced Endpoint ID? URNs help contextualize for humans. Knowing the type tells you which API to use to dereference an ID to an entity.

  • Unambiguous. Without type qualification, any given ID could refer to a number of different entity types. Without knowing the type, it is not always possible to deduce what an ID refers to. e.g. Given the ID of a deleted group it may not be possible to know its type, as it can no longer be resolved by the Groups service.

  • Portable syntax. The syntax is recognizable and parseable across a broad range of services. We can now treat this as a global and uniform way of stringifying these identifiers.

  • Better for Audits. For logging, this gives a canonical string representation of these identifiers with their associated entity types. Logs can then be processed from a range of component services based on these URNs.

  • Flat and Simple Strings. Strings are the simplest, lowest-common-denominator serialization technique. We could use objects, like type: identity, value: 46bd0f56-e24f-11e5-a510-131bef46955c, but that then needs to be represented in different ways in different places (logs, memory, and databases, to start with). URNs are just strings, and look the same everywhere.

Case Sensitivity

Principal URNs are always returned as all-lowercase strings. They are considered case-insensitive on input, but we recommend sending them in lowercase to simplify any comparisons you might perform.

Look Them Up

How can you lookup these values?

Identities

To lookup identities, you need to use the Globus Auth Identities API: https://docs.globus.org/api/auth/reference/#v2_api_identities_resources

A nice and easy way of doing interactive lookups is the Globus CLI:

$ # given urn:globus:auth:identity:46bd0f56-e24f-11e5-a510-131bef46955c
$ globus get-identities 46bd0f56-e24f-11e5-a510-131bef46955c
globus@globus.org

$ # given urn:globus:auth:identity:c0a6b8ac-d274-11e5-bf7e-f33abd9d8cc8
$ globus get-identities c0a6b8ac-d274-11e5-bf7e-f33abd9d8cc8
demo@globus.org

Groups

Given a couple of Group URNs, the same principle applies

  • urn:globus:groups:id:fdb38a24-03c1-11e3-86f7-12313809f035

  • urn:globus:groups:id:fe234176-abe4-11e4-90a3-22000aa401f6

can be seen at

respectively.

There is no public API for fetching Group information.