Friday, December 2, 2022
HomeIOS DevelopmentDissect the PKCE Authorization Code Grant Move on iOS

Dissect the PKCE Authorization Code Grant Move on iOS


Discover ways to use Proof Key for Code Change (PKCE) authentication move to entry APIs along with your Swift iOS apps.

Proof Key for Code Change (PKCE) is an addition to the OAuth authorization framework that protects the authorization move from safety assaults. As knowledge house owners undertake the protocol, it’s obligatory for functions utilizing their APIs to authorize entry utilizing this new protocol.

On this tutorial, you’ll construct an app known as MyGoogleInfo. The app authenticates customers with Google utilizing the OAuth authorization move with PKCE, and it makes use of the Google API to retrieve customers’ profile names and footage.

Right here’s what you’ll study:

  • The OAuth 2.0 authorization code grant move particulars and its vulnerability.
  • What the PKCE authorization move is and the way it strengthens the OAuth move.
  • How you can configure entry to the Google API on the Google Cloud console.
  • How you can implement the PKCE authorization move in Swift to authenticate the person.
  • How you can use the offered token to entry the Google API.

When you have ever questioned how the authentication protocol works or should you’re enthusiastic about utilizing an API from one of many distinguished suppliers to your subsequent undertaking, keep tuned. You’ll get all the small print on this article.

Getting Began

Obtain the starter undertaking by clicking the Obtain Supplies button on the high or backside of the tutorial.

Open MyGoogleInfo.xcodeproj within the starter folder. Construct and run. The Login display will appear like this.

MyGoogleInfo Login screen.

The Login button doesn’t do something but. You’ll implement the PKCE move with the Google OAuth service in PKCEAuthenticationService.

As soon as that’s completed, when the person logs in, MyGoogleInfo presents the person’s profile info.

MyGoogleInfo Profile screen.

Introducing the OAuth 2.0 Authorization Framework

The OAuth 2 Authorization framework is the usual protocol used for consumer authentication. The primary thought behind OAuth authorization is the separation of roles. Particularly, the usual defines a protocol to permit knowledge house owners to delegate purchasers to entry their knowledge, with out giving them their credentials.

Listed below are some phrases to know:

  • Useful resource Proprietor: That is the entity that owns the assets your app want to entry. Sometimes, that is you, holding your knowledge.
  • Consumer: The appliance that wishes to entry the information on the useful resource server, reminiscent of MyGoogleInfo on this case.
  • Authorization server: The server in control of authenticating the person and issuing the tokens to the consumer.
  • Useful resource Server: The server internet hosting the information to entry. An entry token protects the entry to the useful resource server.

Authorization Code Grant Move

This diagram represents the OAuth 2.0 Authorization code grant move that cell functions implement:

OAuth 2.0 Authorization Flow.

  1. The person begins the login move by tapping the MyGoogleInfo Login button.
  2. Consequently, the app asks the authorization server to determine the person and ask their consent to entry the information. The request features a client_id in order that the server can determine the app requesting the entry.
  3. So, the authorization server redirects the person to its login display (e.g. Google) and asks the person’s consent to offer the app entry to the API.
  4. The person logs in and approves the request.
  5. If the person approves the entry, the authorization server returns a grant code to the consumer.
  6. The consumer requests a token to the authorization server, passing its client_id and the obtained grant code.
  7. In response, the authorization server emits a token after verifying the client_id and the grant code.
  8. Lastly, the consumer accesses the information to the useful resource server, authenticating its requests with the token.

For all the small print on this move and the opposite ones outlined in the usual, seek the advice of the RFC 6749: The OAuth 2.0 Authorization Framework (RFC 6749).

Attacking the Authorization Code Grant Move

Though the authorization code grant move is the way in which to go for cell apps, it’s topic to consumer impersonation assaults. A malicious app can impersonate a legit consumer and obtain a sound authentication token to entry the person knowledge.

For the move diagram above, to obtain a token the attacker ought to know these two parameters:

  • The app’s client_id.
  • The code obtained within the callback URL from the authorization token.

Beneath sure circumstances, a malicious app can get better each. The app’s consumer ID is normally hardcoded, for instance, and an attacker might discover it by reverse-engineering the app. Or, by registering the malicious app as a legit invoker of the callback URL, the attacker may sniff the callback URL.

As soon as the attacker is aware of the consumer ID and the grant code, they will request a token to the token endpoint. From that time ahead, they use the entry token to retrieve knowledge illegally.

Introducing PKCE

Proof Key for Code Change (PKCE) is an addition to the Authorization Code Grant move to mitigate the assault depicted above. In observe, it provides a code to every request that’s dynamically generated by the consumer so an attacker can’t guess or intercept it.

The next diagram depicts how PKCE strengthens the Authorization Code Grant move in observe:

OAuth Authorization Flow with PKCE.

That’s to say, PKCE introduces the next modifications with respect to the plain move:

  • [1] That is the place the login move begins.
  • [2] On every login request, the consumer generates a random code (code_verifier) and derives a code_challenge from it.
  • [3] When beginning the move, the consumer contains the code_challenge within the request to the authorization server. On receiving the authorization request, the authorization server saves this code for later verification.
  • [7] The consumer sends the code_verifier when requesting an entry token.
  • [8] Subsequently, the authorization server verifies that code_verifier matches code_challenge. If these two codes match, the server is aware of the consumer is legit and emits the token.

As regards to the earlier assault situation, even when the attacker can intercept the authorization grant code and the code code_challenge, it’s far more tough — if not inconceivable — to intercept the code_verifier.

PKCE is safe, and it’s one of the best ways to implement OAuth authorization move in cell apps.

You will discover all of the PKCE particulars on the RFC 7636 – Proof Key for Code Change by OAuth Public Purchasers.

Now, you’ll take a look at the code verifier/problem technology and the best way to transmit the PKCE parameters with the HTTP requests.

Producing Code Verifier and Problem

The usual itself specifies the best way to generate the code_verifier and code_challenge.

Open PKCECodeGenerator.swift and change the physique of generateCodeVerifier() with:


// 1
var buffer = [UInt8](repeating: 0, rely: 32)
_ = SecRandomCopyBytes(kSecRandomDefault, buffer.rely, &buffer)
// 2
return Information(buffer).base64URLEncodedString()

This generates the code_verifier as follows:

  1. Get a 32-byte random sequence.
  2. Cross the 32 bytes sequence to base64 URL encoder to generate a 43 octet URL protected string.

Now, change the physique of generateCodeChallenge(codeVerifier:) with:


guard let knowledge = codeVerifier.knowledge(utilizing: .utf8) else { return nil }

let dataHash = SHA256.hash(knowledge: knowledge)
return Information(dataHash).base64URLEncodedString()

This derives the code_challenge because the SHA256 hash of the code verifier after which base64 URL encodes it.

Producing HTTP Requests

As well as, the usual specifies two totally different endpoints on the Authorization server for the 2 authorization phases.

Open PKCERequestBuilder.swift and observe the properties for every of those endpoints on the high:

  • Authorization endpoint at /authorize is in control of emitting the authorization code grant.
  • Token endpoint at /token-generation, to emit and refresh tokens.

In response to the RFC, the consumer ought to talk with these two endpoints with two totally different HTTP request sorts:

  • Utilizing a GET with all of the required parameters handed as URL parameters, for the authorization endpoint.
  • Sending a POST with the parameters handed within the request’s physique, encoded as URL parameters, for the token endpoint.

PKCERequestBuilder already accommodates every little thing you want to generate the 2 requests.

  • createAuthorizationRequestURL(codeChallenge:) generates a URL with the required parameters.
  • createTokenExchangeURLRequest(code:codeVerifier:) generates a URLRequest for the token alternate.

Getting ready Server Aspect (Google Cloud Platform)

Earlier than continuing with the consumer implementation, it’s a must to arrange the backend service.

This setup course of means that you can register your software and its redirection URI used all through the authorization move and obtain the clientID.

On this particular instance, since Google already presents a service for person authentication with OAuth, you should use their service.

The service setup course of consists of the next steps:

  • Creating a brand new undertaking.
  • Enabling the precise APIs your app intend to make use of.
  • Producing the authorization credentials for the app (the consumer ID).

You’ll want a Google account to register an app.

Making a New Mission

First, open the Google API Console and click on Create Mission.

Project creation screen.

In the event you’ve beforehand created a undertaking, you may have to click on the identify of the undertaking within the blue bar to deliver up a dialog with a New Mission button.

Screenshot showing how to create a new project when there is an existing one

You may be requested to enroll within the Google Cloud Developer program. In the event you’re not already in, don’t fear — it’s so simple as accepting their phrases and situations.

Enter MyGoogleInfo within the undertaking’s identify. Then, Google assigns you a consumer ID that you just’ll want when you generate the authorization requests from the app.

Click on CREATE.

Project screen.

Enabling the Required API

Now, it’s time to inform Google what sort of API your app will use.

Declaring the required APIs is twofold.

First, it impacts the sort of permission Google presents to the person throughout the authorization section.

And, extra vital, it permits Google to implement the information scope when your app requests knowledge. Every token has a scope that defines which API the token grants entry to.

As an example, within the case of MyGoogleInfo, you want to allow the Google Folks API to permit the app to question the person info.

From the undertaking web page, click on ENABLE APIS AND SERVICES.

Enable APIs screen.

Then, seek for Google Folks API and click on ENABLE.

Google People API screen.

Producing the Authorization Credentials

Lastly, you want to create the authorization credentials earlier than you should use the API.

Click on Credentials within the sidebar.

In the event you see a immediate to configure a consent display, choose exterior person sort and fill out the registration kind for the required fields. Then, click on Credentials within the sidebar once more.

Click on CREATE CREDENTIALS, then select OAuth Consumer ID.

Add credentials menu.

These credentials allow you to specify which entry stage and to which API your customers’ tokens have entry.

Fill within the required fields as proven within the determine beneath.

Most significantly, the Bundle ID ought to have the identical worth because the one set in Xcode to your app. For instance, within the instance beneath, it’s com.alessandrodn.MyGoogleInfo. In your case, it’s your app bundle ID.

OAuth client ID screen.

Lastly, click on CREATE. You need to have an OAuth consumer definition for iOS as within the image beneath:

OAuth client screen.

Exchange REPLACE_WITH_CLIENTID_FROM_GOOGLE_APP within the definition beneath with the Consumer ID out of your Google app in PKCERequestBuilder.

PKCERequestBuilder for MyGoogleInfo.

It took some time to organize, however you’re now able to implement the PKCE consumer in Swift!

Implementing PKCE Consumer in Swift

In spite of everything that idea, it’s now time to get your arms soiled in Xcode :]

Authenticating the Consumer

First, implement the primary section of the authorization move, asking the authorization endpoint to confirm the person identification.

Open PKCEAuthenticationService.swift. Add the next code to the top of startAuthentication():


// 1
let codeVerifier = PKCECodeGenerator.generateCodeVerifier()
guard
  let codeChallenge = PKCECodeGenerator.generateCodeChallenge(
    codeVerifier: codeVerifier
  ),
  // 2
  let authenticationURL = requestBuilder.createAuthorizationRequestURL(
    codeChallenge: codeChallenge
  )
else {
  print("[Error] Cannot construct authentication URL!")
  standing = .error(error: .internalError)
  return
}
print("[Debug] Authentication with: (authenticationURL.absoluteString)")
guard let bundleIdentifier = Bundle.major.bundleIdentifier else {
  print("[Error] Bundle Identifier is nil!")
  standing = .error(error: .internalError)
  return
}
// 3
let session = ASWebAuthenticationSession(
  url: authenticationURL,
  callbackURLScheme: bundleIdentifier
) { callbackURL, error in
  // 4
  self.handleAuthenticationResponse(
    callbackURL: callbackURL,
    error: error,
    codeVerifier: codeVerifier
  )
}
// 5
session.presentationContextProvider = self
// 6
session.begin()

The code above implements the primary a part of the authorization move:

  1. Generates the code verifier and derives the code problem from it.
  2. Put together the authorization endpoint URL with all of the required parameters.
  3. Instantiate ASWebAuthenticationSession to carry out the authentication, passing authenticationURL generated earlier than.
  4. In its completion handler, ASWebAuthenticationSession returns the parameters obtained from the server as callbackURL.
  5. Inform the browser occasion that your class is its presentation context supplier. So, iOS instantiates the system browser window on high of the app’s major window.
  6. Lastly, begin the session.

ASWebAuthenticationSession offers you again an elective callback URL and an elective error.

For now, handleAuthenticationResponse(callbackURL:error:codeVerifier:) parses the error and prints the callback URL.

Construct and run. Faucet the Login button, and also you’ll see an alert saying MyGoogleInfo desires to make use of google.com to check in.

Dialog asking permission to use google.com to sign in

Faucet Proceed and also you’ll see the Google login display.

Notice the Google request to share the person’s profile info.

MyGoogleInfo login screen

Enter your credentials, authorize the app and verify the logs.
Examine the app’s log for the callback URL returned from Google with the authorization response parameters.

Received callback URL log.

Parsing the Callback URL

To proceed with the authorization move, you now have to do two issues.

First, in PKCEAuthenticationService.swift, add the perform getToken(code:codeVerifier:) as follows.


non-public func getToken(code: String, codeVerifier: String) async {
  guard let tokenURLRequest = requestBuilder.createTokenExchangeURLRequest(
    code: code,
    codeVerifier: codeVerifier
  ) else {
    print("[Error] Cannot construct token alternate URL!")
    standing = .error(error: .internalError)
    return
  }
  let tokenURLRequestBody = tokenURLRequest.httpBody ?? Information()
  print("[Debug] Get token parameters: (String(knowledge: tokenURLRequestBody, encoding: .utf8) ?? "")")
  //TODO: make request
}

createTokenExchangeURLRequest() generates the HTTP request, given the grant code and code_verifier.

Notice: The perform getToken(code:codeVerifier:) is async, because it’ll return instantly and full the community name within the background. Because you invoke it from a synchronous context, you utilize a Job.

Then, change the implementation of handleAuthenticationResponse(callbackURL:error:codeVerifier:) with the next.


if let error = error {
  print("[Error] Authentication failed with: (error.localizedDescription)")
  standing = .error(error: .authenticationFailed)
  return
}
guard let code = extractCodeFromCallbackURL(callbackURL) else {
  standing = .error(error: .authenticationFailed)
  return
}
Job {
  await getToken(code: code, codeVerifier: codeVerifier)
}

The code above extracts the code parameter worth within the callback URL and passes it to getToken(code:codeVerifier:).

Construct and run, then log in along with your credentials. Confirm the log now accommodates the parameters for the credential alternate.

Get Token Parameters log.

Getting the Entry Token

Lastly, you’re able to get the token.

Exchange the //TODO: make request remark in getToken(code:codeVerifier:) with the next:


do {
  // 1
  let (knowledge, response) = attempt await URLSession.shared.knowledge(for: tokenURLRequest)
  // 2
  guard let response = response as? HTTPURLResponse else {
    print("[Error] HTTP response parsing failed!")
    standing = .error(error: .tokenExchangeFailed)
    return
  }
  guard response.isOk else {
    let physique = String(knowledge: knowledge, encoding: .utf8) ?? "EMPTY"
    print("[Error] Get token failed with standing: (response.statusCode), physique: (physique)")
    standing = .error(error: .tokenExchangeFailed)
    return
  }
  print("[Debug] Get token response: (String(knowledge: knowledge, encoding: .utf8) ?? "EMPTY")")
  // 3
  let decoder = JSONDecoder()
  decoder.keyDecodingStrategy = .convertFromSnakeCase
  let token = attempt decoder.decode(GoogleToken.self, from: knowledge)
  // TODO: Retailer the token within the Keychain
  // 4
  standing = .authenticated(token: token)
} catch {
  print("[Error] Get token failed with: (error.localizedDescription)")
  standing = .error(error: .tokenExchangeFailed)
}

The perform getToken(code:codeVerifier:) performs the next actions:

  1. Use the tokenURLRequest to begin the token alternate session with the token endpoint. Because of this, it receives again a URLResponse and an elective Information.
  2. Parse the server response standing.
  3. If there aren’t any errors, decode the consequence as a GoogleToken.
  4. Lastly, set the standing to authenticated, together with the entry token as a parameter.

Now you’re prepared to begin querying knowledge. :]

When you get the token, you can begin utilizing it to entry the API.

The code in ViewModel listens to the authentication service standing and passes the token to the GoogleProfileInfoService. Then, the profile information service makes use of the token to entry your profile info.

Construct and run. Log in a single final time. Lastly, you may see your Google profile info.

MyGoogleInfo showing user profile.

You can even see within the logs the token response from the server:

Get token response log.

Storing the Token

To date, you didn’t save the entry token in persistent storage. In different phrases, each time the app begins, the person must log in once more.

To make the person expertise flawless, the app ought to do two extra issues.
First, it ought to save each the entry and the refresh tokens in persistent storage, as quickly as they’re obtained from the server.
Second, it ought to restore the token from the persistent storage when the app begins.

Because the tokens include credential entry, it’s best to keep away from UserDefaults and use the Apple keychain.

Refreshing the Token

The entry token and the refresh token have a restricted timeframe. In different phrases, they’ve a time expiration date enforced on the server.

As soon as the entry token expires, your API calls will fail with error 401. In these instances, you want to set off the token refresh move with the token endpoint. The HTTP request physique accommodates the consumer ID and the refresh token encoded as URL parameters.

For a reference, createRefreshTokenURLRequest(refreshToken:) within the remaining undertaking generates the URLRequest for the token refresh.

The place to Go From Right here?

Obtain the finished undertaking information by clicking the Obtain Supplies button on the high or backside of the tutorial.

You dug into the small print of the OAuth Authorization move with PKCE, and now you’re able to implement the authentication service to your subsequent app. You can even experiment with issues like token administration and higher error dealing with.

For all the small print on the best way to retailer and retrieve the token within the keychain, try How To Safe iOS Consumer Information: Keychain Companies and Biometrics with SwiftUI.

Alternatively, if you wish to undertake one of many SDKs accessible for OAuth, you now know the way PKCE works below the hood to completely management the bundle habits.

For reference, listed here are some third-party SDKs that implement OAuth with PKCE.

  • AppAuth is an open-source SDK from the OpenID consortium; it helps native apps (iOS and Android) and all the opposite Apple OSs and Native JS.
  • Auth0 presents an entire answer for OpenID authentication and, as part of it, they supply an SDK that helps each iOS and macOS.

We hope you loved this tutorial. When you have any questions or feedback, please be part of the discussion board dialogue beneath!

RELATED ARTICLES

LEAVE A REPLY

Please enter your comment!
Please enter your name here

Most Popular

Recent Comments