OpenIddict Resource Configuration

Configuration of Scopes, Claims and Audiences for the OpenID Connect server

Scopes

Scopes define the permissions and information that a client application can request during the authentication process. They represent the level of access granted to OAuth2/OpenID Connect clients.

Supported Standard Scopes:

openid - Unique user identifier
profile - User profile information
email - User email address
address - User physical address
phone - Phone number
roles - User assigned roles
offline_access - Access for refresh tokens

Note: The openid scope is mandatory for OpenID Connect requests. The offline_access scope is required if you want to use refresh tokens.

Claims

Claims are statements about an entity (typically the user) and represent the specific information that gets included in ID tokens and access tokens. Each claim has a name and a value.

Main Configurable Claims:

Identity: sub, preferred_username, nickname
Personal: name, given_name, family_name, middle_name
Contact: email, phone_number, address
Details: birthdate, gender, locale, zoneinfo
Verification: email_verified, phone_number_verified
Profile: profile, picture, website
System: updated_at, iss

What to Configure:

  • • Select only the claims that your application actually uses
  • • Consider privacy: don't expose unnecessary sensitive information
  • • Claims are automatically mapped from user profile when available
  • • Some claims like sub and iss are handled automatically by the system

Audiences

Audiences identify the intended recipients for access tokens. They specify which resources or APIs are authorized to receive and validate tokens issued by the server.

Typical Audience Examples:

GraphQL APIs:GraphQL.Read, GraphQL.Wrtite - Specific GraphQL endpoints that will consume the tokens
Microservices: Individual service identifiers for distributed architectures

Configuration Guidelines:

  • • Each audience should represent a distinct API or resource server
  • • Use meaningful names that clearly identify the target service
  • • Audiences are included in the aud claim of access tokens
  • • Resource servers should validate that they are listed as an audience in received tokens
  • • Consider using URLs or URNs for globally unique audience identifiers

Security Note: Properly configured audiences help prevent token misuse by ensuring tokens are only accepted by their intended recipients.

Quick Configuration Summary

Scopes

Define what information clients can request

Required: openid
Common: profile, email, roles

Claims

Specify user attributes to include in tokens

Select based on application needs
Consider privacy implications

Audiences

Identify which APIs can accept tokens

One per API/service
Use descriptive identifiers