introduce addtional http headers to OIDTokenRequest (#770)

Co-authored-by: Vitalij Dadaschjanz <[email protected]>

Author: break2k

Examples/Example-iOS_ObjC-Carthage/Source/AppAuthExampleViewController.m

@@ -177,7 +177,8 @@ - (void)doClientRegistration:(OIDServiceConfiguration *)configuration
                                                    grantTypes:nil
                                                   subjectType:nil
                                       tokenEndpointAuthMethod:@"client_secret_post"
-                                         additionalParameters:nil];
+                                         additionalParameters:nil
+                                            additionalHeaders:nil];
     // performs registration request
     [self logMessage:@"Initiating registration request"];
 

Examples/Example-iOS_ObjC/Source/AppAuthExampleViewController.m

@@ -179,7 +179,8 @@ - (void)doClientRegistration:(OIDServiceConfiguration *)configuration
                                                    grantTypes:nil
                                                   subjectType:nil
                                       tokenEndpointAuthMethod:@"client_secret_post"
-                                         additionalParameters:nil];
+                                         additionalParameters:nil
+                                            additionalHeaders:nil];
     // performs registration request
     [self logMessage:@"Initiating registration request"];
 

Examples/Example-iOS_Swift-Carthage/Source/AppAuthExampleViewController.swift

@@ -349,7 +349,8 @@ extension AppAuthExampleViewController {
                                                                      grantTypes: nil,
                                                                      subjectType: nil,
                                                                      tokenEndpointAuthMethod: "client_secret_post",
-                                                                     additionalParameters: nil)
+                                                                     additionalParameters: nil,
+                                                                     additionalHeaders: nil)
 
         // performs registration request
         self.logMessage("Initiating registration request")

Examples/Example-tvOS/Example-tvOS/AppAuthTVExampleViewController.m

@@ -176,7 +176,8 @@ - (void)performAuthorizationWithConfiguration:(OIDTVServiceConfiguration *)confi
                                                       clientId:kClientID
                                                   clientSecret:kClientSecret
                                                         scopes:@[ OIDScopeOpenID, OIDScopeProfile ]
-                                          additionalParameters:nil];
+                                          additionalParameters:nil
+                                             additionalHeaders:nil];
 
   OIDTVAuthorizationInitialization initBlock =
       ^(OIDTVAuthorizationResponse *_Nullable response, NSError *_Nullable error) {

README.md

@@ -516,7 +516,8 @@ OIDTVAuthorizationRequest *request =
                                                     clientId:kClientID
                                                 clientSecret:kClientSecret
                                                       scopes:@[ OIDScopeOpenID, OIDScopeProfile ]
-                                        additionalParameters:nil];
+                                        additionalParameters:nil
+                                           additionalHeaders:nil];
 
 // performs authentication request
 OIDTVAuthorizationInitialization initBlock =

Source/AppAuthCore/OIDAuthState.h

@@ -48,6 +48,12 @@ typedef void (^OIDAuthStateAction)(NSString *_Nullable accessToken,
 typedef void (^OIDAuthStateAuthorizationCallback)(OIDAuthState *_Nullable authState,
                                                   NSError *_Nullable error);
 
+/*! @brief The exception thrown when a developer tries to create a refresh request from an
+        authorization request with no authorization code.
+ */
+static NSString *const kRefreshTokenRequestException =
+    @"Attempted to create a token refresh request from a token response with no refresh token.";
+
 /*! @brief A convenience class that retains the auth state between @c OIDAuthorizationResponse%s
         and @c OIDTokenResponse%s.
  */
@@ -267,6 +273,31 @@ typedef void (^OIDAuthStateAuthorizationCallback)(OIDAuthState *_Nullable authSt
 - (nullable OIDTokenRequest *)tokenRefreshRequestWithAdditionalParameters:
     (nullable NSDictionary<NSString *, NSString *> *)additionalParameters;
 
+/*! @brief Creates a token request suitable for refreshing an access token.
+    @param additionalParameters Additional parameters for the token request.
+    @param additionalHeaders Additional headers for the token request.
+    @return A @c OIDTokenRequest suitable for using a refresh token to obtain a new access token.
+    @discussion After performing the refresh, call @c OIDAuthState.updateWithTokenResponse:error:
+        to update the authorization state based on the response. Rather than doing the token refresh
+        yourself, you should use @c OIDAuthState.performActionWithFreshTokens:.
+    @see https://tools.ietf.org/html/rfc6749#section-1.5
+ */
+- (nullable OIDTokenRequest *)tokenRefreshRequestWithAdditionalParameters:
+    (nullable NSDictionary<NSString *, NSString *> *)additionalParameters
+                                                        additionalHeaders:
+    (nullable NSDictionary<NSString *, NSString *> *)additionalHeaders;
+
+/*! @brief Creates a token request suitable for refreshing an access token.
+    @param additionalHeaders Additional parameters for the token request.
+    @return A @c OIDTokenRequest suitable for using a refresh token to obtain a new access token.
+    @discussion After performing the refresh, call @c OIDAuthState.updateWithTokenResponse:error:
+        to update the authorization state based on the response. Rather than doing the token refresh
+        yourself, you should use @c OIDAuthState.performActionWithFreshTokens:.
+    @see https://tools.ietf.org/html/rfc6749#section-1.5
+ */
+- (nullable OIDTokenRequest *)tokenRefreshRequestWithAdditionalHeaders:
+    (nullable NSDictionary<NSString *, NSString *> *)additionalHeaders;
+
 @end
 
 NS_ASSUME_NONNULL_END

Source/AppAuthCore/OIDAuthState.m

@@ -55,12 +55,6 @@
  */
 static NSString *const kAuthorizationErrorKey = @"authorizationError";
 
-/*! @brief The exception thrown when a developer tries to create a refresh request from an
-        authorization request with no authorization code.
- */
-static NSString *const kRefreshTokenRequestException =
-    @"Attempted to create a token refresh request from a token response with no refresh token.";
-
 /*! @brief Number of seconds the access token is refreshed before it actually expires.
  */
 static const NSUInteger kExpiryTimeTolerance = 60;
@@ -427,7 +421,47 @@ - (OIDTokenRequest *)tokenRefreshRequest {
 - (OIDTokenRequest *)tokenRefreshRequestWithAdditionalParameters:
     (NSDictionary<NSString *, NSString *> *)additionalParameters {
 
-  // TODO: Add unit test to confirm exception is thrown when expected
+  if (!_refreshToken) {
+    [OIDErrorUtilities raiseException:kRefreshTokenRequestException];
+  }
+  return [[OIDTokenRequest alloc]
+      initWithConfiguration:_lastAuthorizationResponse.request.configuration
+                  grantType:OIDGrantTypeRefreshToken
+          authorizationCode:nil
+                redirectURL:nil
+                   clientID:_lastAuthorizationResponse.request.clientID
+               clientSecret:_lastAuthorizationResponse.request.clientSecret
+                      scope:nil
+               refreshToken:_refreshToken
+               codeVerifier:nil
+       additionalParameters:additionalParameters
+          additionalHeaders:nil];
+}
+
+- (OIDTokenRequest *)tokenRefreshRequestWithAdditionalParameters:
+    (NSDictionary<NSString *, NSString *> *)additionalParameters
+                                               additionalHeaders:
+    (NSDictionary<NSString *,NSString *> *)additionalHeaders {
+
+  if (!_refreshToken) {
+    [OIDErrorUtilities raiseException:kRefreshTokenRequestException];
+  }
+  return [[OIDTokenRequest alloc]
+      initWithConfiguration:_lastAuthorizationResponse.request.configuration
+                  grantType:OIDGrantTypeRefreshToken
+          authorizationCode:nil
+                redirectURL:nil
+                   clientID:_lastAuthorizationResponse.request.clientID
+               clientSecret:_lastAuthorizationResponse.request.clientSecret
+                      scope:nil
+               refreshToken:_refreshToken
+               codeVerifier:nil
+       additionalParameters:additionalParameters
+          additionalHeaders:additionalHeaders];
+}
+
+- (OIDTokenRequest *)tokenRefreshRequestWithAdditionalHeaders:
+    (NSDictionary<NSString *, NSString *> *)additionalHeaders {
 
   if (!_refreshToken) {
     [OIDErrorUtilities raiseException:kRefreshTokenRequestException];
@@ -442,7 +476,8 @@ - (OIDTokenRequest *)tokenRefreshRequestWithAdditionalParameters:
                       scope:nil
                refreshToken:_refreshToken
                codeVerifier:nil
-       additionalParameters:additionalParameters];
+       additionalParameters:nil
+          additionalHeaders:additionalHeaders];
 }
 
 #pragma mark - Stateful Actions

Source/AppAuthCore/OIDAuthorizationResponse.h

@@ -121,7 +121,9 @@ NS_ASSUME_NONNULL_BEGIN
     @see https://tools.ietf.org/html/rfc6749#section-4.1.3
  */
 - (nullable OIDTokenRequest *)tokenExchangeRequestWithAdditionalParameters:
-    (nullable NSDictionary<NSString *, NSString *> *)additionalParameters;
+    (nullable NSDictionary<NSString *, NSString *> *)additionalParameters
+                                                         additionalHeaders:
+    (nullable NSDictionary<NSString *, NSString *> *)additionalHeaders;
 
 @end
 

Source/AppAuthCore/OIDAuthorizationResponse.m

@@ -184,11 +184,13 @@ - (NSString *)description {
 #pragma mark -
 
 - (OIDTokenRequest *)tokenExchangeRequest {
-  return [self tokenExchangeRequestWithAdditionalParameters:nil];
+  return [self tokenExchangeRequestWithAdditionalParameters:nil additionalHeaders:nil];
 }
 
 - (OIDTokenRequest *)tokenExchangeRequestWithAdditionalParameters:
-    (NSDictionary<NSString *, NSString *> *)additionalParameters {
+    (NSDictionary<NSString *, NSString *> *)additionalParameters
+                                                additionalHeaders:
+    (NSDictionary<NSString *, NSString *> *)additionalHeaders {
   // TODO: add a unit test to confirm exception is thrown when expected and the request is created
   //       with the correct parameters.
   if (!_authorizationCode) {
@@ -204,7 +206,8 @@ - (OIDTokenRequest *)tokenExchangeRequestWithAdditionalParameters:
                                                   scope:nil
                                            refreshToken:nil
                                            codeVerifier:_request.codeVerifier
-                                   additionalParameters:additionalParameters];
+                                   additionalParameters:additionalParameters
+                                      additionalHeaders:additionalHeaders];
 }
 
 @end

Source/AppAuthCore/OIDTokenRequest.h

@@ -95,9 +95,13 @@ NS_ASSUME_NONNULL_BEGIN
  */
 @property(nonatomic, readonly, nullable) NSDictionary<NSString *, NSString *> *additionalParameters;
 
+/*! @brief The client's additional token request headers.
+ */
+@property(nonatomic, readonly, nullable) NSDictionary<NSString *, NSString *> *additionalHeaders;
+
 /*! @internal
     @brief Unavailable. Please use
-        initWithConfiguration:grantType:code:redirectURL:clientID:additionalParameters:.
+        initWithConfiguration:grantType:code:redirectURL:clientID:additionalParameters:additionalHeaders:.
  */
 - (instancetype)init NS_UNAVAILABLE;
 
@@ -113,6 +117,7 @@ NS_ASSUME_NONNULL_BEGIN
     @param refreshToken The refresh token.
     @param codeVerifier The PKCE code verifier.
     @param additionalParameters The client's additional token request parameters.
+    @param additionalHeaders The client's additional token request headers.
  */
 - (instancetype)initWithConfiguration:(OIDServiceConfiguration *)configuration
                grantType:(NSString *)grantType
@@ -123,7 +128,8 @@ NS_ASSUME_NONNULL_BEGIN
                   scopes:(nullable NSArray<NSString *> *)scopes
             refreshToken:(nullable NSString *)refreshToken
             codeVerifier:(nullable NSString *)codeVerifier
-    additionalParameters:(nullable NSDictionary<NSString *, NSString *> *)additionalParameters;
+    additionalParameters:(nullable NSDictionary<NSString *, NSString *> *)additionalParameters
+       additionalHeaders:(nullable NSDictionary<NSString *, NSString *> *)additionalHeaders;
 
 /*! @brief Designated initializer.
     @param configuration The service's configuration.
@@ -139,6 +145,7 @@ NS_ASSUME_NONNULL_BEGIN
     @param refreshToken The refresh token.
     @param codeVerifier The PKCE code verifier.
     @param additionalParameters The client's additional token request parameters.
+    @param additionalHeaders The client's additional token request headers.
  */
 - (instancetype)initWithConfiguration:(OIDServiceConfiguration *)configuration
                grantType:(NSString *)grantType
@@ -150,6 +157,7 @@ NS_ASSUME_NONNULL_BEGIN
             refreshToken:(nullable NSString *)refreshToken
             codeVerifier:(nullable NSString *)codeVerifier
     additionalParameters:(nullable NSDictionary<NSString *, NSString *> *)additionalParameters
+       additionalHeaders:(nullable NSDictionary<NSString *, NSString *> *)additionalHeaders
     NS_DESIGNATED_INITIALIZER;
 
 /*! @brief Designated initializer for NSSecureCoding.