Android SDK guide

This guide will show you how to integrate Logto into your Android application.

Prerequisites​

• A Logto Cloud account or a self-hosted Logto (Check out the ⚡ Get started guide to create one if you don't have).
• A Logto native application created.
• A Kotlin Android application project.

Installation​

Before you install Logto Android SDK, ensure mavenCentral() is added to your repository configuration in the Gradle project build file:

dependencyResolutionManagement {
  repositories {
    mavenCentral()
  }
}

Add Logto Android SDK to your dependencies:

dependencies {
  implementation("io.logto.sdk:android:1.1.3")
}

dependencies {
  implementation 'io.logto.sdk:android:1.1.3'
}

Since the SDK needs internet access, you need to add the following permission to your AndroidManifest.xml file:

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
  xmlns:tools="http://schemas.android.com/tools">

  <!-- add internet permission -->
  <uses-permission android:name="android.permission.INTERNET" />

  <!-- other configurations... -->
</manifest>

Integration​

Init LogtoClient​

Create a LogtoViewModel.kt and init LogtoClient in this view model:

//...with other imports
import io.logto.sdk.android.LogtoClient
import io.logto.sdk.android.type.LogtoConfig

class LogtoViewModel(application: Application) : AndroidViewModel(application) {
    private val logtoConfig = LogtoConfig(
          endpoint = "<your-logto-endpoint>",
          appId = "<your-app-id>",
          scopes = null,
          resources = null,
          usingPersistStorage = true,
    )

    private val logtoClient = LogtoClient(logtoConfig, application)

    companion object {
        val Factory: ViewModelProvider.Factory = object : ViewModelProvider.Factory {
            @Suppress("UNCHECKED_CAST")
            override fun <T : ViewModel> create(
                modelClass: Class<T>,
                extras: CreationExtras
            ): T {
                // Get the Application object from extras
                val application = checkNotNull(extras[APPLICATION_KEY])
                return LogtoViewModel(application) as T
            }
        }
    }
}

then, create a LogtoViewModel for your MainActivity.kt:

//...with other imports
class MainActivity : AppCompatActivity() {
    private val logtoViewModel: LogtoViewModel by viewModels { LogtoViewModel.Factory }
    //...other codes
}

Configure redirect URI​

Before we dive into the details, here's a quick overview of the end-user experience. The sign-in process can be simplified as follows:

1. Your app invokes the sign-in method.
2. The user is redirected to the Logto sign-in page. For native apps, the system browser is opened.
3. The user signs in and is redirected back to your app (configured as the redirect URI).

Let's switch to the Application details page of Logto Console. Add a Redirect URI io.logto.android://io.logto.sample/callback and click "Save changes".

In Android, the redirect URI follows the pattern: $(LOGTO_REDIRECT_SCHEME)://$(YOUR_APP_PACKAGE)/callback:

• The LOGTO_REDIRECT_SCHEME should be a custom scheme in the reverse domain format.
• The YOUR_APP_PACKAGE is your app package name.

Assuming you treat io.logto.android as the custom LOGTO_REDIRECT_SCHEME, and io.logto.sample is your app package name, the Redirect URI should be io.logto.android://io.logto.sample/callback.

Implement sign-in and sign-out​

You can use logtoClient.signIn to sign in the user and logtoClient.signOut to sign out the user.

For example, in an Android app:

//...with other imports
class LogtoViewModel(application: Application) : AndroidViewModel(application) {
    // ...other codes

    // Add a live data to observe the authentication status
    private val _authenticated = MutableLiveData(logtoClient.isAuthenticated)
    val authenticated: LiveData<Boolean>
        get() = _authenticated

    fun signIn(context: Activity) {
        logtoClient.signIn(context, "io.logto.android://io.logto.sample/callback") { logtoException ->
            logtoException?.let { println(it) }
            // Update the live data
            _authenticated.postValue(logtoClient.isAuthenticated)
        }
    }

    fun signOut() {
        logtoClient.signOut { logtoException ->
            logtoException?.let { println(it) }
            // Update the live data
            _authenticated.postValue(logtoClient.isAuthenticated)
        }
    }
}

Then call the signIn and signOut methods in your activity:

class MainActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        //...other codes

        // Assume you have a button with id "sign_in_button" in your layout
        val signInButton = findViewById<Button>(R.id.sign_in_button)
        signInButton.setOnClickListener {
            logtoViewModel.signIn(this)
        }

        // Assume you have a button with id "sign_out_button" in your layout
        val signOutButton = findViewById<Button>(R.id.sign_out_button)
        signOutButton.setOnClickListener {
            if (logtoViewModel.authenticated) { // Check if the user is authenticated
                logtoViewModel.signOut()
            }
        }

        // Observe the authentication status to update the UI
        logtoViewModel.authenticated.observe(this) { authenticated ->
            if (authenticated) {
                // The user is authenticated
                signInButton.visibility = View.GONE
                signOutButton.visibility = View.VISIBLE
            } else {
                // The user is not authenticated
                signInButton.visibility = View.VISIBLE
                signOutButton.visibility = View.GONE
            }
        }

    }
}

Checkpoint: Test your application​

Now, you can test your application:

1. Run your application, you will see the sign-in button.
2. Click the sign-in button, the SDK will init the sign-in process and redirect you to the Logto sign-in page.
3. After you signed in, you will be redirected back to your application and see the sign-out button.
4. Click the sign-out button to clear local storage and sign out.

Get user information​

Display user information​

To display the user's information, you can use the logtoClient.getIdTokenClaims() method. For example, you can get user information in a ViewModel and then display it in your activity:

class LogtoViewModel(application: Application) : AndroidViewModel(application) {
    // ...other codes

    // Add a live data to observe the id token claims
    private val _idTokenClaims = MutableLiveData<IdTokenClaims>()
    val idTokenClaims: LiveData<IdTokenClaims>
        get() = _idTokenClaims

    fun getIdTokenClaims() {
        logtoClient.getIdTokenClaims { logtoException, idTokenClaims ->
            logtoException?.let { _logtoException.postValue(it) } ?: _idTokenClaims.postValue(idTokenClaims)
        }
    }
}

//...with other imports
class MainActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        //...other codes

        // Assume you have a text View with id `user_info_text_view` in your layout
        val userInfoResponseTextView: TextView = findViewById(R.id.user_info_text_view)
        logtoViewModel.userInfoResponse.observe(this) { userInfoResponse ->
            userInfoResponseTextView.text = if (userInfoResponse !== null) {
                val json = Gson().toJson(userInfoResponse, UserInfoResponse::class.java)
                JSONObject(json).toString(2)
            } else {
                ""
            }
        }
    }
}

Request additional claims​

You may find some user information are missing in the returned object from logtoClient.getIdTokenClaims(). This is because OAuth 2.0 and OpenID Connect (OIDC) are designed to follow the principle of least privilege (PoLP), and Logto is built on top of these standards.

By default, limited claims are returned. If you need more information, you can request additional scopes to access more claims.

Here's a non-normative example the scope - claim relationship:

Logto SDK will always request three scopes: openid, profile, and offline_access.

To request additional scopes, you can pass the scopes to the LogtoConfig object. For example:

private val logtoConfig = LogtoConfig(
    // ...other configs
    scopes = listOf("email", "phone"), // or `listOf(UserScope.EMAIL, UserScope.PHONE)`
)

Then you can access the additional claims in the return value of logtoClient.getIdTokenClaims():

logtoClient.getIdTokenClaims { logtoException, idTokenClaims ->
    println("IdTokenClaims:$idTokenClaims")
}
// Now you can access additional claims `claims.email`, `claims.phone`, etc.

Claims that need network requests​

To prevent bloating the ID token, some claims require network requests to fetch. For example, the custom_data claim is not included in the user object even if it's requested in the scopes. To access these claims, you can use the logtoClient.fetchUserInfo() method:

logtoClient.fetchUserInfo {_, userInfoResponse ->
  println("UserInfoResponse:$userInfoResponse")
}
// Now you can access the claim `userInfo.custom_data`

Scopes and claims​

Logto uses OIDC scopes and claims conventions to define the scopes and claims for retrieving user information from the ID token and OIDC userinfo endpoint. Both of the "scope" and the "claim" are terms from the OAuth 2.0 and OpenID Connect (OIDC) specifications.

Here's the list of supported scopes and the corresponding claims:

openid

profile

Other standard claims include family_name, given_name, middle_name, nickname, preferred_username, profile, website, gender, birthdate, zoneinfo, and locale will be also included in the profile scope without the need for requesting the userinfo endpoint. A difference compared to the claims above is that these claims will only be returned when their values are not empty, while the claims above will return null if the values are empty.

email

phone

address

Please refer to the OpenID Connect Core 1.0 for the details of the address claim.

custom_data

identities

urn:logto:scope:organizations

urn:logto:scope:organization_roles

Considering performance and the data size, if "Needs userinfo?" is "Yes", it means the claim will not show up in the ID token, but will be returned in the userinfo endpoint response.

API resources and organizations​

We recommend to read 🔐 Role-Based Access Control (RBAC) first to understand the basic concepts of Logto RBAC and how to set up API resources properly.

Configure Logto client​

Once you have set up the API resources, you can add them when configuring Logto in your app:

val logtoConfig = LogtoConfig(
    //...other configs
    resources = listOf("https://shopping.your-app.com/api", "https://store.your-app.com/api"), // Add API resources
)

Each API resource has its own permissions (scopes).

For example, the https://shopping.your-app.com/api resource has the shopping:read and shopping:write permissions, and the https://store.your-app.com/api resource has the store:read and store:write permissions.

To request these permissions, you can add them when configuring Logto in your app:

val logtoConfig = LogtoConfig(
    // ..other configs
    scopes = listOf("shopping:read", "shopping:write", "store:read", "store:write"),
    resources = listOf("https://shopping.your-app.com/api", "https://store.your-app.com/api"),
)

You may notice that scopes are defined separately from API resources. This is because Resource Indicators for OAuth 2.0 specifies the final scopes for the request will be the cartesian product of all the scopes at all the target services.

Thus, in the above case, scopes can be simplified from the definition in Logto, both of the API resources can have read and write scopes without the prefix. Then, in the Logto config:

val logtoConfig = LogtoConfig(
    // ...other configs
    scopes = listOf("read", "write"),
    resources = listOf("https://shopping.your-app.com/api", "https://store.your-app.com/api"),
)

For every API resource, it will request for both read and write scopes.

After the successful sign-in, Logto will issue proper scopes to API resources according to the user's roles.

Fetch access token for the API resource​

To fetch the access token for a specific API resource, you can use the getAccessToken method:

logtoClient.getAccessToken("https://shopping.your-app.com/api") { logtoException, accessToken ->
    logtoException?.let { println(it) }
    accessToken?.let { println(it) }
}

This method will return a JWT access token that can be used to access the API resource when the user has related permissions. If the current cached access token has expired, this method will automatically try to use a refresh token to get a new access token.

Fetch organization tokens​

If organization is new to you, please read 🏢 Organizations (Multi-tenancy) to get started.

You need to add UserScope.Organizations scope when configuring the Logto client:

val logtoConfig = LogtoConfig(
    // ...other configs
    scopes = listOf(UserScope.Organizations),
)

Once the user is signed in, you can fetch the organization token for the user:

// Replace the parameter with a valid organization ID.
// Valid organization IDs for the user can be found in the ID token claim `organizations`.
logtoClient.getOrganizationToken("organization-id") { logtoException, organizationToken ->
    logtoException?.let { println(it) }
    organizationToken?.let { println(it) }
}

// or
logtoClient.getOrganizationTokenClaims("organization-id") { logtoException, claims ->
    logtoException?.let { println(it) }
    claims?.let { println(it) }
}

Organization API resources​

To fetch an access token for an API resource in an organization, you can use the getAccessToken method with both the API resource and organization ID as parameters:

logtoClient.getAccessToken(
  'https://shopping.your-app.com/api',
  organizationId
) { logtoException, accessToken ->
    println("AccessToken:$accessToken")
}

Further readings​

• Customize sign-in experience
• Configure connectors
• Protect your API