You specified a custom claim but that claim isn’t being returned

In Hosted Login (and in OAuth in general), a “claim” typically represents a single piece of user information: the user’s first name is a claim, the user’s gender is a claim, the city that the user lives in is a claim. Hosted Login supports a number of standard OAuth claims, and makes it easy for you to return this information as part of the user’s identity token and/or to make that information accessible from the userinfo endpoint following a successful login.

In addition to that, Hosted Login supports the use of “custom claims.” A custom claim is simply a non-standard claim tied to an attribute in your user profile schema. For example, the organization that a user is associated with (the primaryAddress.company attribute) is not one of the standard OAuth claims; that means that you can’t use a standard claim to return the value of the primaryAddress.company attribute. However, you can create a custom claim that does return that information. That’s not hard to do; it’s just a little tricky.

If you’ve used the OpenID Connect Playground then you might have tried your hand at creating a custom claim. If so, you probably did something similar to this, entering the name of the user schema attribute (primaryAddress.company) and then adding this custom claim to either the userinfo profile or the identity token (or both):

And then you submitted your authorization request, checked the userinfo response, and saw this:

Sigh.

But don’t give up;: we’re about to explain the tricky part mentioned earlier. When you request a custom claim you can’t just enter an attribute name in the request. Instead, you first have to add that custom claim to your login policy. In other words, your login policy needs to have a customClaims property that looks something like this:

"customClaims": {
      "id_token":
           {"organization": "primaryAddress.company"},
      "userinfo":
           {"organization": "primaryAddress.company"}
    }

What we’ve done here is define a custom claim named organization that maps to the primaryAddress.company attribute; we’ve also added this claim to both the identity token (id_token) and the userinfo endpoint. Any custom claim you include in your authorization request must be defined in your login policy. If it’s not, then the request will simply be ignored.

After you’ve updated your login policy then you can add the custom claim to your authorization request, making sure that you reference the claim by claim name (organization) rather than by schema attribute name. (Although the claim name and the schema attribute name can be the same.) For example:

And that’s how you return a custom claim: