Userinfo

The userinfo endpoint in OpenID Connect (OIDC) provides user profile information based on the scopes requested during the authorization process. This guide explains how to use the userinfo endpoint and interpret the user information returned.

Overview

The userinfo endpoint responds with user profile information according to the scopes requested by the client. Common scopes include address, email, phone, and profile. Each scope allows access to specific user information.

Scopes and Claims

1. Address Scope

When the address scope is requested, the userinfo endpoint includes the user's address details in the response. The address fields typically include:

• street_address: The street address of the user.
• locality: The city or locality of the user.
• region: The state or region of the user.
• postal_code: The postal code of the user.
• country: The country of the user.

Example response for the address scope:

{
    "address": {
        "street_address": "123 Main St",
        "locality": "Anytown",
        "region": "CA",
        "postal_code": "12345",
        "country": "USA"
    }
}

2. Email Scope

When the email scope is requested, the userinfo endpoint includes the user's email address in the response.

Example response for the email scope:

{
    "email": "user@example.com"
}

3. Phone Scope

When the phone scope is requested, the userinfo endpoint includes the user's phone number in the response.

Example response for the phone scope:

{
    "phone": "+1234567890"
}

4. Profile Scope

When the profile scope is requested, the userinfo endpoint includes basic profile information about the user. This can include:

• name: The full name of the user.
• family_name: The family name or last name of the user.
• given_name: The given name or first name of the user.
• nickname: A casual name to address the user.
• profile: URL of the user's profile page.
• picture: URL of the user's profile picture.
• website: URL of the user's web page.
• gender: The gender of the user.
• birthdate: The birthdate of the user in the format "YYYY-MM-DD".
• zoneinfo: The user's time zone.
• locale: The user's locale, typically an ISO 639-1 language code plus a country code.
• updated_at: Timestamp of when the user's information was last updated.

Example response for the profile scope:

{
    "name": "John Doe",
    "family_name": "Doe",
    "given_name": "John",
    "nickname": "Johnny",
    "profile": "https://example.com/johndoe",
    "picture": "https://example.com/johndoe.jpg",
    "website": "https://johndoe.com",
    "gender": "male",
    "birthdate": "1980-01-01",
    "zoneinfo": "America/Los_Angeles",
    "locale": "en-US",
    "updated_at": 1609459200
}

Example Usage

Here’s how to use the userinfo endpoint to retrieve user information:

1. Define the Scopes

Define the scopes you want to request during the authorization process:

const scopes = ['openid', 'profile', 'email', 'address', 'phone'];

2. Get an Access Token

Follow the authorization and token exchange process to obtain an access token. This typically involves redirecting the user to the authorization endpoint and then exchanging the authorization code for tokens at the token endpoint.

3. Retrieve User Information

Use the access token to call the userinfo endpoint and retrieve user information. Here’s an example using axios in Node.js:

const axios = require('axios');

const config = {
    method: 'get',
    url: 'https://ed.link/api/authentication/oidc/userinfo',
    headers: {
        Authorization: 'Bearer ACCESS_TOKEN'
    }
};

axios
    .request(config)
    .then((response) => {
        console.log(JSON.stringify(response.data));
    })
    .catch((error) => {
        console.log(error);
    });

Replace ACCESS_TOKEN with the actual token received from the token endpoint.

Complete Example Flow

1. Initiate Authorization Request:

   const authorizationUrl = `https://ed.link/api/authentication/oidc/authorize?response_type=code&client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI&scope=openid%20profile%20email%20address%20phone&state=RANDOM_STATE`;
   window.location.href = authorizationUrl;
   

2. Exchange Authorization Code for Tokens:

   const axios = require('axios');
   const qs = require('qs');
   
   const data = qs.stringify({
       grant_type: 'authorization_code',
       code: 'AUTHORIZATION_CODE',
       redirect_uri: 'YOUR_REDIRECT_URI',
       client_id: 'YOUR_CLIENT_ID',
       client_secret: 'YOUR_CLIENT_SECRET'
   });
   
   const config = {
       method: 'post',
       url: 'https://ed.link/api/authentication/oidc/token',
       headers: {
           'Content-Type': 'application/x-www-form-urlencoded'
       },
       data: data
   };
   
   axios
       .request(config)
       .then((response) => {
           console.log(JSON.stringify(response.data));
       })
       .catch((error) => {
           console.log(error);
       });
   

3. Retrieve User Information:

   const axios = require('axios');
   
   const config = {
       method: 'get',
       url: 'https://ed.link/api/authentication/oidc/userinfo',
       headers: {
           Authorization: 'Bearer ACCESS_TOKEN'
       }
   };
   
   axios
       .request(config)
       .then((response) => {
           console.log(JSON.stringify(response.data));
       })
       .catch((error) => {
           console.log(error);
       });
   

Conclusion

The userinfo endpoint in OIDC allows clients to retrieve detailed user information based on the requested scopes. By following this guide, you can effectively use the userinfo endpoint to obtain and handle user profile information in your application.