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:
GET https://#yourdomain/admin/oauth2/authorize.idp?client_id=...&redirect_uri=...response_type=...&scope=openid fed:local:claim1&response_mode=...
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 | |
| 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 |
- The above claims are mapped when generating access tokens, id tokens, and Userinfo's response.
- 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:
"userinfo_signing_alg_values_supported":["RS256","HS256","HS384","HS512"]
Dynamic client registration endpoint
Please visit the Client metadata section for the new supported keys:
| Key name |
|---|
| userinfo_signed_response_alg |
Protocol
Setting up OAuth 2.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 OAuth 2.0 protocol connection:
For the Safewhere Admin, you can find the option in the OpenID Connect/OAuth 2.0 application's security settings:
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:
POST https://#yourdomain/runtime/openidconnect/userinfo.idp
Content-Type: application/x-www-form-urlencoded
Request body example:
| Key | Value |
|---|---|
| access_token | eyJhbGciO...VKVzRqME1 |
Response example:
eyJhbGciOiJ...aSMNTd0tlHuY-o6uFMcg