Delightful Apps

Authenticating with a web service

2020-03-09T07:00:00+00:00

Knowing who you are is a difficult thing at the best of times. Allowing an app to authenticate against a web service is likewise as difficult due to the level of trust that needs to be created between you and the system handling the authentication. Thankfully Apple has a solution to the authentication problem known as ASWebAuthenticationSession that exists as part of the AuthenticationServices framework.

So what makes authentication a difficult? Can’t we just send username and password in the clear? The answer to that is simple. No, we can’t. We need to make sure that who we are authenticating against is who we expect. We need to make sure that we create the trust between our app and the web service. Let’s look at how this is done.

The first component we want is ASWebAuthenticationSession, though in order to make use of that we need to build a few things first. By doing this, we are able to expose parts of AppKit or UIKit to SwiftUI so that ASWebAuthenticationSession does it thing. So what does it require? It requires a ASPresentationAnchor. This typically is a window being either an NSWindow or an UIWindow. In the land of SwiftUI, this is done through an environment variable. Let’s build this out.

struct WindowKey: EnvironmentKey {
    static let defaultValue: NSWindow? = nil
}

extension EnvironmentValues {
    var window: NSWindow? {
        get {
            self[WindowKey.self]
        }
        set {
            self[WindowKey.self] = newValue
        }
    }
}

So what exactly does that do? It provides our SwiftUI views with the knowledge of the window and we’ll use that later on. We’ll move on and start building out the app parts. First up is the view that will allow us to present everything. As you guessed, it’s a button that we tap.

struct AuthView: View {
  @Environment(\.window) var window: NSWindow?
  let store: AuthStore

  var body: some View {
    VStack(alignment: .center, spacing: 16.0) {
      Button(action: {
        self.store.auth()
      }) {
        Text("Login with GitHub")
          .font(.headline)
      }
    }
  }
}

There are a few bits we need to fill out here, the first of which is our AuthStore. Lets look at this and how it’s pieced together.

final class AuthStore {
  private var helper: AuthHelper?
  private var authCancellable: AnyCancellable? {
    willSet {
      authCancellable?.cancel()
    }
  }

  init(window: NSWindow?) {
    helper = AuthHelper(window: window)
  }

  func auth() {
    authCancellable = helper?.authenticate()
      .sink(receiveCompletion: { completion in

      }, receiveValue: { apiKey in
        if AuthKeychainHelper.tokenExists {
          try? AuthKeychainHelper.update(token: apiKey)
        } else {
          try? AuthKeychainHelper.store(token: apiKey)
        }
      })
  }
}

This involves one piece that we wont touch on being the Keychain helper. Suffice to say, it’s for storing the resulting api token. The piece of interest though is the AuthHelper which handles our interaction with ASWebAuthenticationSession. The full implementation will be placed at the end, but for now we’ll break apart the interesting pieces.

To begin, we have the type that conforms to ASWebAuthenticationPresentationContextProviding and tells us how the web auth window should be presented. When dealing with ASWebAuthenticationSession we want to be providing it with an instance of this type.

class AuthServiceContextProvider: NSObject, ASWebAuthenticationPresentationContextProviding {
  let window: NSWindow

  init(window: NSWindow) {
    self.window = window
  }

  func presentationAnchor(for session: ASWebAuthenticationSession) -> ASPresentationAnchor {
    return window
  }
}

The second part is our call to ASWebAuthenticationSession. We are wrapping this in a Future so that it’s exposed to SwiftUI using Combine.

  func authenticate() -> AnyPublisher<String, Errors> {
    let scopes = [
      "user",
      "public_repo",
      "repo",
      "repo:status",
      "read:org"
    ]

    var urlComponents = URLComponents(string: "")
    urlComponents?.queryItems = [
      URLQueryItem(name: "client_id", value: "abc123"),
      URLQueryItem(name: "scope", value: scopes.joined(separator: " "))
    ]

    guard let url = urlComponents?.url else {
      return Fail(error: Errors.invalidURL).eraseToAnyPublisher()
    }

    return Future<String, Errors> { promise in
      let session = ASWebAuthenticationSession(url: url, callbackURLScheme: "appscheme") { (url, error) in
        if let error = error as? ASWebAuthenticationSessionError {
          switch error.code {
          case .canceledLogin:
            promise(.failure(.userCancelled))
          default:
            promise(.failure(.unknown))
          }
        }

        if let url = url, let oauthToken = URLComponents(url: url, resolvingAgainstBaseURL: false)?.queryItems?.filter({ $0.name == "code" }).first?.value {
          promise(.success(oauthToken))
        } else {
          promise(.failure(.noToken))
        }
      }

      session.presentationContextProvider = self.contextProvider
      session.start()
    }
    .flatMap(fetchToken(with:))
    .receive(on: RunLoop.main)
    .eraseToAnyPublisher()
  }

Here we have asked ASWebAuthenticationSession to authenticate against the given URL (in my projects case, GitHub). The second interesting part is what we do with the token we get back. Unfortunately what GitHub returns us isn’t the final api token we use for requests. We need to make another call to get that. This happens in the fetchToken(with:) function. Let’s unpack that now.

There’s a curiosity here in the code. What exactly is the callbackURLScheme? This is how the service knows to call back into your app once you have been authenticated. You’ll need to set this up in your info.plist. The scheme you define there is the one you provide here.

  private func fetchToken(with token: String) -> AnyPublisher<String, Errors> {
    var components = URLComponents(string: "")
    let queryItems: [URLQueryItem] = [
      URLQueryItem(name: "client_id", value: "123abc"),
      URLQueryItem(name: "client_secret", value: "abc123"),
      URLQueryItem(name: "code", value: token)
    ]

    components?.queryItems = queryItems

    guard let url = components?.url else {
      return Fail(error: .invalidURL).eraseToAnyPublisher()
    }

    var request = URLRequest(url: url)
    request.addValue("application/json", forHTTPHeaderField: "Accept")
    request.httpMethod = "POST"

    return URLSession.shared
      .dataTaskPublisher(for: request)
      .map { $0.data }
      .decode(type: Response.self, decoder: decoder)
      .mapError { error in
        if let error = error as? Errors {
          return error
        }

        return Errors.jsonDecoding
      }
      .map { $0.accessToken }
      .eraseToAnyPublisher()
  }

The result of this is our api token after having been authenticated with the web service.

As mentioned, the entire implementation of the auth helper is included.

class AuthHelper {
  struct Response: Decodable {
    let accessToken: String
    let scope: String
    let tokenType: String

    enum CodingKeys: String, CodingKey {
      case accessToken = "access_token"
      case scope
      case tokenType = "token_type"
    }
  }

  enum Errors: Error {
    case invalidURL
    case userCancelled
    case noToken
    case unknown
    case jsonDecoding
  }

  private var contextProvider: AuthServiceContextProvider
  private var decoder: JSONDecoder

  init?(window: NSWindow?, environment: AppEnvironment) {
    guard let window = window else { return nil }

    contextProvider = AuthServiceContextProvider(
      window: window
    )
    self.decoder = JSONDecoder()
  }

  func authenticate() -> AnyPublisher<String, Errors> {
    let scopes = [
      "user",
      "public_repo",
      "repo",
      "repo:status",
      "read:org"
    ]

    var urlComponents = URLComponents(string: "")
    urlComponents?.queryItems = [
      URLQueryItem(name: "client_id", value: ""),
      URLQueryItem(name: "scope", value: scopes.joined(separator: " "))
    ]

    guard let url = urlComponents?.url else {
      return Fail(error: Errors.invalidURL).eraseToAnyPublisher()
    }

    return Future<String, Errors> { promise in
      let session = ASWebAuthenticationSession(url: url, callbackURLScheme: "") { (url, error) in
        if let error = error as? ASWebAuthenticationSessionError {
          switch error.code {
          case .canceledLogin:
            promise(.failure(.userCancelled))
          default:
            promise(.failure(.unknown))
          }
        }

        if let url = url, let oauthToken = URLComponents(url: url, resolvingAgainstBaseURL: false)?.queryItems?.filter({ $0.name == "code" }).first?.value {
          promise(.success(oauthToken))
        } else {
          promise(.failure(.noToken))
        }
      }

      session.presentationContextProvider = self.contextProvider
      session.start()
    }
    .flatMap(fetchToken(with:))
    .receive(on: RunLoop.main)
    .eraseToAnyPublisher()
  }

  private func fetchToken(with token: String) -> AnyPublisher<String, Errors> {
    var components = URLComponents(string: "")
    let queryItems: [URLQueryItem] = [
      URLQueryItem(name: "client_id", value: ""),
      URLQueryItem(name: "client_secret", value: ""),
      URLQueryItem(name: "code", value: token)
    ]

    components?.queryItems = queryItems

    guard let url = components?.url else {
      return Fail(error: .invalidURL).eraseToAnyPublisher()
    }

    var request = URLRequest(url: url)
    request.addValue("application/json", forHTTPHeaderField: "Accept")
    request.httpMethod = "POST"

    return URLSession.shared
      .dataTaskPublisher(for: request)
      .map { $0.data }
      .decode(type: Response.self, decoder: decoder)
      .mapError { error in
        if let error = error as? Errors {
          return error
        }

        return Errors.jsonDecoding
      }
      .map { $0.accessToken }
      .eraseToAnyPublisher()
  }
}

I hope this has been an insightful article. One that allows you to build some amazing products. If you are after help in such amazing applications, please do get in touch using the links below.

Transitions in SwiftUI

2020-03-07T07:00:00+00:00

What makes an app delightful? Everyone has a different opinion but when you perform an interaction, the transition needs to be smooth. It has to respond quickly. It must make use of the behaviours that are part of the system. When Apple introduced iOS 13 in 2019, they introduced a change to the way that modals get presented. Gone are the days of a modal covering the entirity of the screen, now is the time of a sheet. A sheet is slightly different in that it is presented almost to the top of the screen. This is a good change and one that allows for the user to understand a part of the app is presented over another and is meant to be a short lived interaction which can be dismissed at will to get back to the main content of the app.

So what if this isn’t the behaviour we want? What if, we want to change the users context from A to B without the ability to dismiss B to get back to A? Well, that’s a bit more complex. We need to get a little bit fancy. So, sit back, relax with a drink, place on your favourite record and lets explore what’s involved in creating this interaction.

To understand the structure of the views, we’ll take a look at the hierarchy of the views involed. In this article, we’ll be using SwiftUI. First up, let’s look at the canvas we’ll be displaying things on.

ZStack(alignment: .center) {
  Text("Hello world")
}
.edgesIgnoringSafeArea(.all)

This places a view on the screen that is extended to the absolute edges of the screen. It ignores the safe area insets. But this is just a single view that’s representing our main app context. The A state. Now lets add in our B state. The modal that covers all of A.

ZStack(alignment: .center) {
  Text("Hello world")

  ZStack(alignment: .center) {
    Text("You're awesome")
  }
  .frame(maxWidth: .infinity, maxHeight: .infinity)
  .background(Color.blue)
  .edgesIgnoringSafeArea(.all)
}
.edgesIgnoringSafeArea(.all)

Here we have the second ZStack covering all of the first. But there’s no interactivity between the two. They are simply layered on top of each other. In order to have the B state displayed as a result of an interaction, we must introduce some state. This is done by using the @State property wrapper around a boolean. This will give us our show / hide behaviour of the B state. It looks like the following:

struct ContentView: View {
  @State var isPresented: Bool = false
  var body: some View {
    ZStack {
      Button(action: {
        self.isPresented.toggle()
      }) {
        Text("Hello, World!")
      }

      if isPresented {
        ZStack(alignment: .center) {
          Button(action: {
            self.isPresented.toggle()
          }) {
            Text("Dismiss modal!")
              .foregroundColor(.black)
          }
        }
        .frame(maxWidth: .infinity, maxHeight: .infinity)
        .background(Color.blue)
        .edgesIgnoringSafeArea(.all)
      }
    }
  }
}

This gives us our show / hide of the view but it doesn’t include any delight. There’s no animation. There’s no transition. It just appears, then it disappears. The tap of the screen, the instantaneous change. Nothing smooth about it. We are provided with some handy view modifiers which give us control over these behaviours. These modifiers are .animation and .transition.

Let’s explore these modifiers a bit. First, .animation. What this provides us with is the timing curve over which a view is changed. Apple’s documentation provides us with a list of the properties and functions that can be applied. There’s also a well written tutorial that steps through the behaviour from apple. There’s also a great article from Paul Hudson on hacking with swift about it as well.

So what does that give us? It lets us say at what speed we would like the view to be animated in and out. If we want to get fancy, we can even specify a spring animation very similar to what is available in UIKit.

Adding .animation to our view is only part of the solution. We also need to say how we want the transition to happen. This modifier takes an AnyTransition type that specifies the style of transition. There are a lot of predefined options here. These even include the ability to combine transitions and have a different transition for insertion and removal. The transition we are after is move and we want it to happen from the bottom edge. This is .move(edge: .bottom). Placing all of these together we get a view like the following.

struct ContentView: View {
  @State var isPresented: Bool = false
  var body: some View {
    ZStack {
      Button(action: {
        withAnimation {
          self.isPresented.toggle()
        }
      }) {
        Text("Hello, World!")
      }

      if isPresented {
        ZStack(alignment: .center) {
          Button(action: {
            withAnimation {
              self.isPresented.toggle()
            }
          }) {
            Text("Dismiss modal!")
              .foregroundColor(.black)
          }
        }
        .frame(maxWidth: .infinity, maxHeight: .infinity)
        .background(Color.blue)
        .edgesIgnoringSafeArea(.all)
        .transition(.move(edge: .bottom))
        .animation(.easeInOut)
      }
    }
  }
}

There we have it, we now have an overly simplified way of presenting a modal view full screen using an animation that comes up from the bottom of the screen and disappears in the same mannor.

We are able to see that it’s very easy to add a delightful animation and transition to the presentation of a view. From here, we hope you go and create some amazingly beautiful products that bring a lot of delight to users. If you’re after help with that, please get in touch using the social links at the bottom of this page.