Introducing the "org" claim

With the release of our B2B SaaS functionality, we needed a mechanism to communicate which organization a user belongs to. A domain name is a common human memorable identifier for an organization, just like email is for a user. But it has similar issues with email being used as the index into a DB, but the domain is similarly useful for linking an existing org record. There are lots of other unique identifiers for organizations including DUNS, LEI, EIN, and VAT. This led us to create an org claim as an object that could hold a Hellō org , and a domain name, and other identifiers in the future:

"org": {
   "id": "org_9yMcnK3agJyUDxOBp19gpSe8_PU1",
   "domain": "hello.coop"
}

We also wanted to identify which of the claims came from the organization, and created org_claims which lists which claims in the ID Token were issued by the org.

These new claims ( org and org_claims ) are included in any id_token where the user chose to use a managed account. There is nothing you need to do different as a developer, but you can take advantage of new features when making an authorization request.

domain_hint

Following the lead of Microsoft and Google, we have added support for domain_hint in the authorization request. This allows an application to indicate which organization they want the user to login with. This is useful for provider initiated login, as including the domain_hint in the URL will signal to Hellō which organization to have the user log in with. For example:

https://application.example/api/hellocoop?iss=https%3A%2F%2Fissuer.hello.coop&domain_hint=enterprise.example

Will start a login for a user from enterprise.example at application.example

If you don’t know the organization the user belongs to, and you want to require a managed account, you can include domain_hint=managed in the authorization request. Conversely, if you only want a personal account, you can include domain_hint=personal. See the Authorization Request documentation for more details, or try it out in the Hellō Playground.