Setting scopes and getting claims, through a social connection

Help
,
2

You’re not barking up the wrong tree, don’t worry about it! Yours are very good questions for what it is an unfortunately complicated subject.
Let me try to explain a few different things:

  • Auth0 communicates with each of the external identity providers (“Social” and “Enterprise” type connections) with different protocol. This part should be as transparent as possible (you never really know what happens in that communication) but a byproduct of that is that the information provided by each identity provider differs, both in terms of the available fields and the naming of those fields.
    Auth0 tries to normalize that information but it’s important to understand that some of it might just be unavailable (like the email address on Yahoo connections).
    The information you get from each connection type is a combination of:

    • The information asked to the identity provider, based on the configuration specific to the connection (if available)
    • The configuration done at the identity providers. Some identity providers, when configuring the “Auth0” application on their side, will let you configure how much information to send.
    • What the identity provider decides to send on each case (the could depend on user settings, privacy policies that change over time or whatever)
    • What Auth0 chooses to keep or discard from the information received although, in general, pretty much all the information received is kept.

  • Auth0 stores all the information obtained from the identity provider in the internal user profile, the one that you can go check in the Users section of the dashboard. The first page, under Identity Provider Attributes, lists what we really got about the user. If you don’t see it there, it’s either a limitation of the connection type, a misconfiguration of the connection (e.g. the type of information asked to the identity provider) or a configuration issue at the identity provider itself.

  • Applications that authenticate with Auth0 will usually do so using the OIDC protocol. We support other protocols like SAML and WS-Federation, but OIDC is the one pushed in all of the quickstarts and SDKs because of its simplicity and consistency.

  • The OIDC specification defines some “scopes” that applications can ask for, and a list of “claims” that will be returned for each scope (assuming the claims are available at the user profile). These are:

    • profile: This scope value requests access to the End-User’s default profile Claims, which are: name,family_name, given_name, middle_name, nickname, preferred_username, profile, picture, website,gender, birthdate, zoneinfo, locale, and updated_at.

    • email: This scope value requests access to the email and email_verified Claims.

    • address: This scope value requests access to the address Claim.

    • phone: This scope value requests access to the phone_number and phone_number_verified Claims.

    • In addition to the above, the openid scope is what enables the OIDC protocol to get information about the user and that scope adds the sub (which is the user_id) to the list of returned claims.

  • The “Connection tester” (the “Try” button in the dashboard for connections) works like any other application requesting an authentication to do the test, and requests the openid profile scope only. So the “It works!” page only displays the claims mentioned above for these scopes. Other claims might have been retrieved and stored, but they weren’t asked for by the connection tester.

If you want the email and username you will need to ask for the openid profile email scopes. The username, when available, will be either in the nickname (most likely) or in the preferred_username claims.

Pretty much every OIDC SDK out there will allow you to specify which scopes you want, and if you search for the “openid” or “openid profile” strings you will most likely find how to change the scopes. For example, in the Angular 2+ Quickstart you’ll see this code:

  auth0 = new auth0.WebAuth({
    clientID: 'YOUR_CLIENT_ID',
    domain: 'YOUR_AUTH0_DOMAIN',
    responseType: 'token id_token',
    redirectUri: 'http://localhost:3000/callback',
    scope: 'openid' // here you can add profile email
  });

Finally, if you want to give the application claims that are in the user profile that aren’t in the OIDC specification (e.g. “favorite_color” or “role”) , you can do so by creating Custom claims in a rule. Those custom claims will have to be namespaced to be allowed.

Hope all of the above helps to provide a clearer picture.

2 Likes