Userinfo endpoint

Userinfo endpoint

We reworked the Userinfo endpoint to make it issue proper claims as stated by the specification in version 5.5.

Identify supports requesting claims using scope values . Thus, instead of returning all the user's claims as we did previously, it selectively returns claims granted by users which are determined via access token's scopes.

Therefore, there are 3 groups of claims that can be returned from the Userinfo endpoint:

  • Default claims: those claims always are issued regardless of what the requested scopes are.
    • sub: subject of an access token.
    • name: Identify looks up a claim whose name is "name" on the user's claims. Alternatively, it returns the value of the sub claim.
    • urn:internal:userid: this claim is always available for all local user's requests.
  • Standard scopes: depending on the standard scopes of an access token, Identify returns different standard claims as follows:
    • "email" scope: Identify returns "email" and "email_verified" claims. For the "email_verified" claim, Identify always returns "false" since we don't have a mechanism to verify emails yet.
    • "phone" scope: Identify returns "phone_number" and "phone_number_verified " claims. For the "phone_number_verified" claim, Identify always returns "false" since we don't have a mechanism to verify phone numbers yet.
    • "address": Identify looks up an "address" claim and return it if there is. Otherwise, Identify skips this claim. (Note: the address value must be JSON object)
    • "profile" scope: Identify looks up a set of claims and return them if there are any proper ones. Those claims are "profile", "family_name", "given_name", "middle_name", "nickname", "preferred_username", "picture", "website", "gender", "birthdate", "zoneinfo", "locale", "updated_at".
  • Additional scopes: if an OIDC application wants to request for additional claims from the Userinfo endpoint, it needs to specifically request for them by adding them as requested scopes to the login request sent to Identify. For instance, if you want to request for a fed:local:claim1 claim, the request will look like:

Please note that Identify only returns those claims if it can find them in user's claims. As a side note, our OIDC application samples have a setting to specify what scopes and claims you want to request.

Another change is that Identify OAuth 2.0/OIDC won't issue the user_id claim anymore. Instead, the user's ID is now issued via the urn:internal:userid claim type.

Note: while serializing token (both id token and access token) to JSON strings, some claim types are mapped from JWT to .NET claims as followings:

From claim To claim
http://schemas.xmlsoap.org/ws/2009/09/identity/claims/actor actor
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/dateofbirth birthdate
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress email
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname family_name
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/gender gender
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname given_name
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier nameid
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier sub
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/webpage website
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name unique_name
http://schemas.microsoft.com/identity/claims/objectidentifier oid
http://schemas.microsoft.com/identity/claims/scope scp
http://schemas.microsoft.com/identity/claims/tenantid tid
http://schemas.microsoft.com/claims/authnclassreference acr
http://schemas.xmlsoap.org/claims/EmailAddress adfs1email
http://schemas.xmlsoap.org/claims/UPN adfs1upn
http://schemas.microsoft.com/claims/authnmethodsreferences amr
http://schemas.microsoft.com/ws/2008/06/identity/claims/authenticationinstant auth_time
http://schemas.microsoft.com/ws/2008/06/identity/claims/authenticationmethod authmethod
http://schemas.microsoft.com/2012/12/certificatecontext/extension/applicationpolicy certapppolicy
http://schemas.microsoft.com/2012/12/certificatecontext/extension/authoritykeyidentifier certauthoritykeyidentifier
http://schemas.microsoft.com/2012/12/certificatecontext/extension/basicconstraints certbasicconstraints
http://schemas.microsoft.com/2012/12/certificatecontext/extension/eku certeku
http://schemas.microsoft.com/2012/12/certificatecontext/field/issuer certissuer
http://schemas.microsoft.com/2012/12/certificatecontext/field/issuername certissuername
http://schemas.microsoft.com/2012/12/certificatecontext/extension/keyusage certkeyusage
http://schemas.microsoft.com/2012/12/certificatecontext/field/notafter certnotafter
http://schemas.microsoft.com/2012/12/certificatecontext/field/notbefore certnotbefore
http://schemas.microsoft.com/2012/12/certificatecontext/extension/certificatepolicy certpolicy
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/rsa certpublickey
http://schemas.microsoft.com/2012/12/certificatecontext/field/rawdata certrawdata
http://schemas.microsoft.com/ws/2008/06/identity/claims/serialnumber certserialnumber
http://schemas.microsoft.com/2012/12/certificatecontext/field/signaturealgorithm certsignaturealgorithm
http://schemas.microsoft.com/2012/12/certificatecontext/field/subject certsubject
http://schemas.microsoft.com/2012/12/certificatecontext/extension/san certsubjectaltname
http://schemas.microsoft.com/2012/12/certificatecontext/extension/subjectkeyidentifier certsubjectkeyidentifier
http://schemas.microsoft.com/2012/12/certificatecontext/field/subjectname certsubjectname
http://schemas.microsoft.com/2012/12/certificatecontext/extension/certificatetemplateinformation certtemplateinformation
http://schemas.microsoft.com/2012/12/certificatecontext/extension/certificatetemplatename certtemplatename
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/thumbprint certthumbprint
http://schemas.microsoft.com/2012/12/certificatecontext/field/x509version certx509version
http://schemas.microsoft.com/2012/01/requestcontext/claims/x-ms-client-application clientapplication
http://schemas.microsoft.com/2012/01/requestcontext/claims/x-ms-client-ip clientip
http://schemas.microsoft.com/2012/01/requestcontext/claims/x-ms-client-user-agent clientuseragent
http://schemas.xmlsoap.org/claims/CommonName commonname
http://schemas.microsoft.com/ws/2008/06/identity/claims/denyonlyprimarygroupsid denyonlyprimarygroupsid
http://schemas.microsoft.com/ws/2008/06/identity/claims/denyonlyprimarysid denyonlyprimarysid
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/denyonlysid denyonlysid
http://schemas.microsoft.com/2012/01/devicecontext/claims/displayname devicedispname
http://schemas.microsoft.com/2012/01/devicecontext/claims/identifier deviceid
http://schemas.microsoft.com/2012/01/devicecontext/claims/ismanaged deviceismanaged
http://schemas.microsoft.com/2012/01/devicecontext/claims/ostype deviceostype
http://schemas.microsoft.com/2012/01/devicecontext/claims/osversion deviceosver
http://schemas.microsoft.com/2012/01/devicecontext/claims/userowner deviceowner
http://schemas.microsoft.com/2012/01/devicecontext/claims/registrationid deviceregid
http://schemas.microsoft.com/2012/01/requestcontext/claims/x-ms-endpoint-absolute-path endpointpath
http://schemas.microsoft.com/2012/01/requestcontext/claims/x-ms-forwarded-client-ip forwardedclientip
http://schemas.xmlsoap.org/claims/Group group
http://schemas.microsoft.com/ws/2008/06/identity/claims/groupsid groupsid
http://schemas.microsoft.com/identity/claims/identityprovider idp
http://schemas.microsoft.com/ws/2012/01/insidecorporatenetwork insidecorporatenetwork
http://schemas.microsoft.com/2012/01/devicecontext/claims/isregistereduser isregistereduser
ClaimTypes.PPID ppid
http://schemas.microsoft.com/ws/2008/06/identity/claims/primarygroupsid primarygroupsid
http://schemas.microsoft.com/ws/2008/06/identity/claims/primarysid primarysid
http://schemas.microsoft.com/2012/01/requestcontext/claims/x-ms-proxy proxy
http://schemas.microsoft.com/ws/2012/01/passwordchangeurl pwdchgurl
http://schemas.microsoft.com/ws/2012/01/passwordexpirationdays pwdexpdays
http://schemas.microsoft.com/ws/2012/01/passwordexpirationtime pwdexptime
http://schemas.microsoft.com/2012/01/requestcontext/claims/relyingpartytrustid relyingpartytrustid
http://schemas.microsoft.com/ws/2008/06/identity/claims/role role
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn upn
http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname winaccountname
  1. The above claims are mapped when generating access tokens, id tokens, and Userinfo's response.
  2. If a user has more than one email value, the first one is used for the email claim of Userinfo's response.

UserInfo response signing

Identify supports signing for userinfo response as described on spec. When it's signed, its claims are returned in a JWT and the content-type is application/jwt.

Discovery endpoint

You can check the discovery endpoint of your Identify instance to see if the userinfo_signing_alg_values_supported feature has been supported:

Dynamic client registration endpoint

Please visit the Client metadata section for the new supported keys:

Key name
userinfo_signed_response_alg

Protocol

Setting up OAuth2.0 protocol connection for UserInfo response signing

You update the settings below:

  • Enable the option: "Sign UserInfo response".
  • Select the algorithm: RSASigning or HMACSynmetric at JWS Algorithm. If HMACSynmetric is selected, you can alter to generate Symmetric key for HMAC signing: 32-byte key(HS256)/48-byte key(HS384)/64-byte key(HS512).

For the Identify Admin, you can find the options in the OAuth2.0 protocol connection:

identify-admin-userinfo-signing

For the Safewhere Admin, you can find the option in the OpenID Connect/OAuth2.0 application's security settings:

sw-admin-userinfo-signing

For the REST API, you can add a property named "signUserInfoResponse" into its "configuration" connection JSON element.

Client side

After specifying the UserInfo response signing, you call POST/GET method to the userinfo endpoint.

Request URL using POST:

Request body example:

Key Value
access_token eyJhbGciOiJSUzI1NiIsImtpZCI6IlBCX1hOYVFEWGp0NDB6UkUzbE1udzVPcUtDNCIsIng1dCI6IlBCX1hOYVFEWGp0NDB6UkUzbE1udzVPcUtDNCIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJDZkRKOFBNMkNlTUJ4NXBCakhod1NBMHprREc0QjBPMk94V0c5RHZ6U0k1RVBOOE1mTUwxWWRyNU0zbWdWNnNHSVpVck45REpKc2N6Q1RHNDc5S3Zqd0Q1OUNGSHJIemdkZjQwZnRQSlJ1QVVKVzRqME1...

Response example: