iOS SDK
Integrate your iOS application with Authgear iOS SDK
Last updated
Integrate your iOS application with Authgear iOS SDK
Last updated
This guide provides instructions on integrating Authgear with an iOS app. Supported platforms include:
iOS 11.0 or higher
Follow this guide to add Authgear to your iOS app in 🕐 10 minutes.
You can find the full code for the demo app for this tutorial in this Github repo
Sign up for an Authgear Portal account at https://portal.authgear.com/. Or you can use your self-deployed Authgear.
From the Project listing, create a new Project or select an existing Project. After that, we will need to create an Authgear client application in the project.
Go to Applications on the left menu bar.
Click ⊕Add Application in the top toolbar.
Input the name of your application and select Native App as the application type. Click "Save".
You will see a list of guides that can help you for setting up, then click "Next".
Here you'll need to define a custom URI scheme that Authgear will use to redirect users back to your app after authentication. For our example app, this URL Scheme will be com.example.authgeardemo://host/path
. For further instructions on setting up a custom URI scheme in iOS, see the official documentation here.
Head back to Authgear Portal, and add com.example.authgeardemo://host/path
as Redirect URI.
Click "Save" button and note the Client ID. and Endpoint for your new client application as you'll use them later in your iOS application. You can also obtain the Client ID again from the Applications list later.
In this step, we'll add user authentication to a simple iOS app using the Authgear iOS SDK and the client application we created in the previous steps.
To follow the steps in this guide seamlessly, you should have the following:
Xcode (Latest Version)
Some knowledge of SwiftUI
For the purpose of this guide, we'll create a new project in Xcode. Skip this step if you're adding Authgear to your existing app.
To create a new project, open Xcode and navigate to File > New > Project. Create your new project with the following details:
Project Name: my_demo_app
choose SwiftUI
as Interface Leave other fields unchanged and proceed to create the project.
The Authgear iOS SDK makes it easy to interact with Authgear services from your iOS project.
To add Authgear SDK to your project, in Xcode navigate to File > Add Package Dependencies and enter https://github.com/authgear/authgear-sdk-ios.git
in the Package URL text field.
Click Add Package to proceed.
On the next screen, select your application under Add to Target then click on Add Package.
Alternatively, if your project uses cocoapods, install the SDK using:
In this step, we'll initialize an instance of the Authgear SDK when the user interface of our app loads.
In a production app, you may want to initialize Authgear at the entry point of your app. E.g. For SwiftUI projects, this is usually a file with a name like YourProjectNameApp.swift or AppDelegate for storyboard projects.
For our demo app, add the following code to ContentView.swift
First import Authgear iOS SDK:
In struct ContentView: View {}
, initialize an instance of Authgear()
and call the .configure()
method in an .onAppear()
modifier attached to VStack
like this:
Replace "<CLIENT_ID>" and "<AUTHGEAR_ENDPOINT>" with the client ID and endpoint from the configuration page of the client project you created earlier.
Now let's add the Login button and other UI elements for the demo app.
Add the following views to VStack
:
In addition to the Login button, we've included a ProgressView and a block with views we want only logged-in users to see. Create the isLoading
, userId
and loginState
variables that the if-statement and Text view depend on at the top of the class just after private var authgear: Authgear = Authgear(...)
:
Implement a startAuthentication()
method in your ContentView
class that will call the authenticate()
method of the Authgear SDK:
In order to get your app to build at this point, add empty declarations for logout and openUserSettings methods:
The full code for ContentView.swift
at this point should look like this:
Run your app now. When you click on the Login button, you should be redirected to the user authentication page.
Open your project's Info.plist
or project settings UI in Xcode and add the following:
Navigate to Targets > {Your project} > Info and expand the URL Types section.
Add a new URL scheme with the following details:
Identifier: CFBundleURLTypes
URL Schemes: com.example.authgeardemo://host/path
Role: Editor
Now run your app again and try logging in. Because we've set up a redirect URL, Authgear should redirect back to our app correctly.
Implement the logout method that will be executed when the Logout button is clicked by updating the empty logout function we added in the previous step:
Now clicking on the Logout button will call Authgear SDK's logout method and end the current user session.
In some cases, you may need to obtain current user info through the SDK. (e.g. Display email address in the UI). Use the fetchUserInfo
function to obtain the user info, see example.
The Authgear SDK can return the current user's details via the UserInfo object. The authenticate method returns this userInfo object as demonstrated earlier in our app's startAuthentication()
method. You can also call the SDK's .fetchUserInfo()
method to get the UserInfo object.
Add a new getCurrentUser()
method to your ContentView
class:
Now call the new getCurrentUser()
method in the .onAppear()
modifier of the VStack
like this:
This will make your app refresh the access token and greet users who are already logged in with their sub
(a unique user ID) when the launch the app. You can read other user attributes like email address, phone number, full name, etc. from userInfo.
Authgear offers a pre-built User Settings page that user's can use to view, and modify their profile attributes and security settings.
Implement the empty openUserSettings()
method we added in the previous step to call the .open()
method of the Authgear SDK:
When you start launching the application. You may want to know if the user has logged in. (e.g. Show users a Login button if they haven't logged in).
The sessionState
reflects the user logged-in state in the SDK local state. That means even if the sessionState
is .authenticated
, the session may be invalid if it is revoked remotely. Hence, after initializing the Authgear SDK, call fetchUserInfo
to update the sessionState
as soon as it is proper to do so. We demonstrated how to use sessionState
, and fetchUserInfo
, to get a user's true logged-in state and retrieve their UserInfo in Step 8.
The value of sessionState
can be .unknown
, .noSession
or .authenticated
. Initially, the sessionState
is .unknown
. After a call to authgear.configure
, the session state would become .authenticated
if a previous session was found, or .noSession
if such session was not found.
Call refreshAccessTokenIfNeeded
every time before using the access token, the function will check and make the network call only if the access token has expired. Include the access token in the Authorization header of your application request.
To protect your application server from unauthorized access. You will need to integrate your backend with Authgear.
Backend/API IntegrationFor detailed documentation on the iOS SDK, visit iOS SDK Reference.