Class ClaimsPrincipalExtensions

Namespace

NuvTools.Security.Extensions

Assembly

NuvTools.Security.dll

Provides extension methods for extracting user information from ClaimsPrincipal objects.

public static class ClaimsPrincipalExtensions

Inheritance

object

ClaimsPrincipalExtensions

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

These extensions simplify the process of extracting common user identity information from claims, handling multiple claim type variations and validating values where appropriate.

Methods

GetCustomAttributeValues<T>(ClaimsPrincipal, string)

Gets all values from a custom extension attribute claim and parses them as the specified type.

public static IEnumerable<T>? GetCustomAttributeValues<T>(this ClaimsPrincipal user, string customAttributeName)

Parameters

user ClaimsPrincipal

The claims principal representing the user.

customAttributeName string

The name of the custom attribute (without the "extension_" prefix).

Returns

IEnumerable<T>

A collection of parsed values, or null if the claim doesn't exist. Invalid values are filtered out for enum types.

Type Parameters

T

The type to parse the attribute values as (string, int, double, bool, or enum).

Examples

// Get a list of role IDs stored as integers in an extension attribute
var roleIds = user.GetCustomAttributeValues<int>("roleIds");

// Get an enum value from a custom attribute
var permissions = user.GetCustomAttributeValues<PermissionLevel>("permissions");

Remarks

This method looks for a claim with type "extension_{customAttributeName}" and expects a comma-separated list of values. It parses each value to the specified type.

Supported types: string, int, double, bool, and enum types.

This is commonly used with Azure AD B2C custom attributes that are passed as extension claims.

Exceptions

NotSupportedException

Thrown when the type T is not supported.

FormatException

Thrown when values cannot be parsed to the specified type.

GetEmail(ClaimsPrincipal)

Gets the email address of the user, checking multiple claim sources and validating the format.

public static string? GetEmail(this ClaimsPrincipal user)

Parameters

user ClaimsPrincipal

The claims principal representing the user.

Returns

string

A valid email address, or null if not found or invalid.

Remarks

This method checks the following claims in order: Email, email (OIDC), UPN, PreferredUsername, UniqueName. The value is validated to ensure it's a properly formatted email address before returning.

GetFamilyName(ClaimsPrincipal)

Gets the family name (last name) of the user from the OIDC family_name claim.

public static string? GetFamilyName(this ClaimsPrincipal user)

Parameters

user ClaimsPrincipal

The claims principal representing the user.

Returns

string

The user's family name, or null if not present.

Remarks

This uses the OIDC standard "family_name" claim. For traditional ASP.NET claims, use GetSurname(ClaimsPrincipal) instead.

GetGivenName(ClaimsPrincipal)

Gets the given name (first name) of the user.

public static string? GetGivenName(this ClaimsPrincipal user)

Parameters

user ClaimsPrincipal

The claims principal representing the user.

Returns

string

The user's given name, or null if not present.

GetId(ClaimsPrincipal)

Gets the unique identifier of the user from either the NameIdentifier or Sub claim.

public static string GetId(this ClaimsPrincipal user)

Parameters

user ClaimsPrincipal

The claims principal representing the user.

Returns

string

The user's unique identifier.

Remarks

This method first tries to get the NameIdentifier claim, then falls back to the Sub claim. At least one of these claims must be present.

Exceptions

InvalidOperationException

Thrown when neither NameIdentifier nor Sub claim is present.

GetName(ClaimsPrincipal)

Gets the display name of the user.

public static string? GetName(this ClaimsPrincipal user)

Parameters

user ClaimsPrincipal

The claims principal representing the user.

Returns

string

The user's display name, or null if not present.

Remarks

This method checks both the standard ClaimTypes.Name and the "name" claim.

GetNameIdentifier(ClaimsPrincipal)

Gets the name identifier claim of the user.

public static string? GetNameIdentifier(this ClaimsPrincipal user)

Parameters

user ClaimsPrincipal

The claims principal representing the user.

Returns

string

The name identifier, or null if not present.

Remarks

This is typically used in ASP.NET Identity-based authentication systems.

GetPreferredUsername(ClaimsPrincipal)

Gets the preferred username of the user.

public static string? GetPreferredUsername(this ClaimsPrincipal user)

Parameters

user ClaimsPrincipal

The claims principal representing the user.

Returns

string

The preferred username, or null if not present.

Remarks

This is a standard OIDC claim representing the user's preferred display username.

GetSub(ClaimsPrincipal)

Gets the subject identifier (sub claim) of the user.

public static string? GetSub(this ClaimsPrincipal user)

Parameters

user ClaimsPrincipal

The claims principal representing the user.

Returns

string

The subject identifier, or null if not present.

Remarks

The 'sub' claim is the standard JWT claim for the unique user identifier.

GetSurname(ClaimsPrincipal)

Gets the surname (last name) of the user from the Surname claim.

public static string? GetSurname(this ClaimsPrincipal user)

Parameters

user ClaimsPrincipal

The claims principal representing the user.

Returns

string

The user's surname, or null if not present.

Remarks

This uses the standard ClaimTypes.Surname claim type. For OIDC tokens, use GetFamilyName(ClaimsPrincipal) instead.

GetUniqueName(ClaimsPrincipal)

Gets the unique name of the user.

public static string? GetUniqueName(this ClaimsPrincipal user)

Parameters

user ClaimsPrincipal

The claims principal representing the user.

Returns

string

The unique name, or null if not present.

Remarks

This is often used in legacy authentication systems as a unique identifier.

GetUpn(ClaimsPrincipal)

Gets the User Principal Name (UPN) of the user.

public static string? GetUpn(this ClaimsPrincipal user)

Parameters

user ClaimsPrincipal

The claims principal representing the user.

Returns

string

The UPN, or null if not present.

Remarks

UPN is commonly used in Microsoft Azure AD and Active Directory scenarios. It typically has the format username@domain.

HasValue<T>(ClaimsPrincipal, string, T)

Determines whether the user has a specific value in a custom extension attribute claim.

public static bool HasValue<T>(this ClaimsPrincipal user, string customAttriuteName, T value)

Parameters

user ClaimsPrincipal

The claims principal representing the user.

customAttriuteName string

The name of the custom attribute (without the "extension_" prefix).

value T

The value to check for.

Returns

bool

True if the user has the specified value in the custom attribute; otherwise, false.

Type Parameters

T

The type to parse the attribute values as (string, int, double, bool, or enum).

Remarks

This method looks for a claim with type "extension_{customAttributeName}" and checks if the specified value exists in the comma-separated list of values.