Accessing User Information

Agile.Now implements OpenID Connect, providing a userinfo endpoint that returns claims about the authenticated user. This endpoint is particularly useful for developers looking to obtain user profile details after authentication.

User Info Endpoint:

To retrieve user profile information, send a GET request to:

GET https://<server-url>/oauth/rest/v2/default/me/userinfo

Remember to replace <server-url> with the actual URL of your Agile.Now server.

Supported Scopes:

The userinfo endpoint supports various scopes that align with the data you wish to retrieve. These scopes include:

• profile
• email
• phone
• roles
• identifier

Include these scopes in your authorization request to ensure the userinfo response contains the desired claims.

User Info Response:

Upon a successful request to the userinfo endpoint, the response includes a JSON object with the user's claims, structured as follows:

Email and Phone Verification

The userinfo response includes email_verified and phone_number_verified claims to indicate whether the user's email and phone number have been validated by the identity provider.

• email_verified: A boolean value that shows whether the email address is verified. (true if verified, false otherwise)
• phone_number_verified: A boolean value that shows whether the phone number is verified. (true if verified, false otherwise)

Example JSON Response from userinfo:

{
  "sub": "248289761001",
  "name": "John Doe",
  "given_name": "John",
  "family_name": "Doe",
  "email": "john.doe@example.com",
  "email_verified": true,
  "phone_number": "+1234567890",
  "phone_number_verified": true,
  "locale": "en-US",
  "profile": "https://example.com/johndoe"
}

Handling Bearer Token Errors:

To access the userinfo endpoint, include a Bearer token in the Authorization header. If the token is invalid, you'll receive an error response.

Error Response Example:

{
   "error":"Unauthorized",
   "error_description":"The session ID or OAuth token used has expired or is invalid.",
   "Errors": [
     "The session ID or OAuth token used has expired or is invalid."
   ],
   "Type": "/Errors/Unauthorized",
   "Title": "Unauthorized",
   "StatusCode": 401,
   "Instance": "/oauth/rest/v2/me/userinfo"
}

Error Handling Tips:

• Always pass a valid Bearer token in the Authorization header.
• Implement token refresh logic in your application to handle expired tokens.
• Use secure HTTPS connections to prevent token interception and leakage.

Best Practices for Developers:

• Ensure scopes requested during the authorization process match those needed for userinfo retrieval.
• Store and manage Bearer tokens securely within your application.
• Handle user data obtained from userinfo with care, respecting privacy and data protection laws.

By integrating the userinfo endpoint into your application, you can provide a more personalized user experience, leveraging the rich set of user claims available through Agile.Now.