MSALClaimsRequest

Objective-C

@interface MSALClaimsRequest
    : NSObject <MSALJsonSerializable, MSALJsonDeserializable>

Swift

class MSALClaimsRequest : NSObject, MSALJsonSerializable, MSALJsonDeserializable

OpenID Connect allows you to optionally request the return of individual claims from the UserInfo Endpoint and/or in the ID Token. A claims request is represented as a JSON object that contains a list of requested claims.

The Microsoft Authentication Library (MSAL) for iOS and macOS allows requesting specific claims in both interactive and silent token acquisition scenarios. It does so through the claimsRequest parameter.

There are multiple scenarios where this is needed. For example:

  • Requesting claims outside of the standard set for your application.
  • Requesting specific combinations of the standard claims that cannot be specified using scopes for your application. For example, if an access token gets rejected because of missing claims, the application can request the missing claims using MSAL.

See more info here: https://openid.net/specs/openid-connect-core-1_0-final.html#ClaimsParameter

Example of Claims Request serialized to json:

{
   "access_token":
   {
       "capolids": {"essential":true, "values":["00000000-0000-0000-0000-000000000001"]}
   },
   "id_token":
   {
    "auth_time": {"essential": true},
    "acr": {"values": ["urn:mace:incommon:iap:silver"]}
   }
}

Note

MSALClaimsRequest is NOT thread safe.

Note

MSAL bypasses the access token cache whenever a claims request is specified. It’s important to only provide claimsRequest parameter when additional claims are needed (as opposed to always providing same claimsRequest parameter in each MSAL API call).

Constructing MSALClaimsRequest

  • Adds a request for a specific claim to be included in the target via the claims request parameter. If claim request alredy exists, provided claim request takes its place.

    Declaration

    Objective-C

    - (BOOL)requestClaim:(nonnull MSALIndividualClaimRequest *)request
           forTarget:(MSALClaimsRequestTarget)target
               error:(NSError *_Nullable *_Nullable)error;

    Swift

    func requestClaim(_ request: MSALIndividualClaimRequest, for target: MSALClaimsRequestTarget) throws

    Parameters

    request

    Individual claim request.
    target

    Target of individual claim.
    error

    The error that occurred during requesting the claim.

    Return Value

    YES if operation was successful, NO otherwise.

  • Remove requested claims for the target.

    Declaration

    Objective-C

    - (BOOL)removeClaimRequestWithName:(nonnull NSString *)name
                            target:(MSALClaimsRequestTarget)target
                             error:(NSError *_Nullable *_Nullable)error;

    Swift

    func removeClaim(withName name: String, target: MSALClaimsRequestTarget) throws

    Parameters

    name

    of requested claim.
    target

    Target of individual claim.
    error

    The error that occurred during removing the claim request.

    Return Value

    YES if operation was successful, NO otherwise.

Read components of MSALClaimsRequest