Skip to main content
Version: v1

Integrate With Beyond Identity

This guide describes how to use Beyond Identity for authentication during an OAuth2 authorization flow.

Prerequisites

Before calling Embedded.shared.authenticate, we must Authorize With Beyond Identity

Authorize With Beyond Identity

Using the Web

The library follows the best practices set out in RFC 8252 - OAuth 2.0 for Native Apps including using SFAuthenticationSession and SFSafariViewController on iOS for the auth request. UIWebView and WKWebView are explicitly not supported due to the security and usability reasons explained in Section 8.12 of RFC 8252.

  • Step 1: Configuring the Authenticator Config

Make sure the Authenticator Config in the Beyond Identity Console is set to type Embedded and that the Invoke URL points to your application with either an App Scheme or a Universal Link.

  • Step 2: Beyond Identity Authorize URL

To begin the authentication flow, start an ASWebAuthenticationSession, and launch your crafted Beyond Identity OAuth2 authorization request URL you built in the pre-requisite step.

let session = ASWebAuthenticationSession(
url: viewModel.beyondIdentityURL,
callbackURLScheme: viewModel.callbackScheme
completionHandler: { (url, error) in }
)
session.presentationContextProvider = self
session.start()
  • Step 3: Invoke URL

During the session completionHandler, a URL with the invoke URL scheme should be returned. When the webpage loads a URL, call Embedded.shared.authenticate. You can confirm the validity of the URL with Embedded.shared.isAuthenticateUrl.

let session = ASWebAuthenticationSession(
url: viewModel.beyondIdentityURL,
callbackURLScheme: viewModel.callbackScheme
){ (url, error) in
guard Embedded.shared.isAuthenticateUrl(url) else {/*not valid*/}
Embedded.shared.authenticate(
url: url,
credentialID: id
) { result in
switch result {
case let .success(response):
case let .failure(error):
}
}
}
  • Step 4: Redirect URL

A redirectURL is returned from a successful authenticate response. The authorization code and the state parameter are attached to this URL. You can exchange the code for an id token using your Beyond Identity Token Endpoint.

Embedded.shared.authenticate(
url: url,
credentialID: id
) { result in
switch result {
case let .success(response):
let code = parseCode(from: response.redirectURL)
let token = exchangeForToken(code)
case let .failure(error):
}
}

Full Example

let session = ASWebAuthenticationSession(
url: viewModel.beyondIdentityURL,
callbackURLScheme: viewModel.callbackScheme
){ (url, error) in
guard Embedded.shared.isAuthenticateUrl(url) else {
print("url is not valid")
return
}
presentCredentialSelection { selectedID in
Embedded.shared.authenticate(
url: url,
credentialID: selectedID
) { result in
switch result {
case let .success(response):
let code = parseCode(from: response.redirectURL)
let token = exchangeForToken(code)
case let .failure(error):
print(error)
}
}
}
}
session.presentationContextProvider = self
session.start()

private fun presentCredentialSelection(callback: (CredentialID) -> Void) {
// Where you can perform some logic here to select a credential, or
// present UI to a user to enable them to select a credential.
}