Posted by John Zoeller – Developer Relations Engineer

This submit is a part of Put on OS Highlight Week. Right now, we’re specializing in implementing Credential Supervisor on Put on OS, aiming to streamline the authentication expertise.

For all software program builders, crafting a quick and safe authentication circulate is paramount, and that is equally vital on Put on OS.

The normal Put on OS strategies require customers to have their cellphone close by to finish authentication, usually with a separate cellular circulate or 2-factor auth code.

Credential Supervisor‘s arrival simplifies this course of, permitting for authentication instantly from a consumer’s watch without having for a close-by cellphone.

As a unified API, Credential Supervisor lets you reuse your cellular app’s code on Put on OS, streamlining improvement throughout kind elements. With a single faucet, customers can authenticate with passwords, federated identities like Check in with Google, or passkeys, the brand new trade normal for safety.

The ability of passkeys

Passkeys are constructed on the precept of uneven encryption. Throughout creation, a system authenticator generates a novel, mathematically linked pair of keys: a public key that’s securely saved on-line with the service, and a personal key that continues to be solely on the consumer’s machine.

When signing in, the machine makes use of the personal key to cryptographically show to the service that it possesses the important thing.

This course of is extremely safe as a result of the personal key by no means leaves the machine throughout authorization (solely throughout syncs from credential suppliers) and may solely be used with the consumer’s express permission. This makes passkeys immune to server breaches, as a breach might solely ever expose the general public half of the important thing pair. Moreover, since there isn’t a passphrase to steal, passkeys are just about phishing-proof.

The consumer expertise of passkeys is seamless: to log in, a consumer confirms their presence with their machine’s lock (e.g., biometric credential or PIN), and they’re signed in. This eliminates the necessity to keep in mind advanced passphrases and gives a quicker, safer methodology of authentication that works seamlessly throughout units.

Designing authentication with Credential Supervisor

Credential Supervisor needs to be the bottom of a Put on app’s authentication circulate. Builders ought to determine which of its built-in strategies to implement based mostly on what’s applied of their cellular experiences, and based mostly on the number of authentication strategies their customers want.

Passkeys are the popular built-in resolution on account of their inherent safety and ease, however the different built-in choices Credential Supervisor gives will also be applied. Passwords are precious due to their familiarity to customers, and federated identities like Check in with Google present customers with the consolation of a trusted supplier.

Builders ought to preserve a minimum of one in all their current authentication choices as a backup as they transition their customers to Credential Supervisor. If Credential Supervisor is dismissed by a consumer, or if all of its strategies fail, or if credentials aren’t out there, builders can current their backup choices.

The Put on Authentication developer information contains particulars on supported Put on OS backup authentication choices. These embrace options like OAuth 2.0, which has historically been a preferred alternative on Put on OS; and knowledge layer token sharing, which can be utilized to robotically authenticate customers at app launch time if their cellphone is close by to sync a signed in account.

Learn the total Put on sign-in design steerage to find out about all one of the best practices for designing your authentication circulate, together with our particular steerage round knowledge layer token sharing.

Implementing Credential Supervisor on Put on OS

Fundamental GetCredential setup

At its core, Credential Supervisor consolidates a number of authentication strategies right into a single, unified API name: getCredential. By configuring a GetCredentialRequest along with your authentication choices, you should utilize the response to validate a consumer’s id along with your app’s server that accommodates the credentials, like so:

val request = GetCredentialRequest(getCredentialOptions())
val getCredentialResponse = credentialManager.getCredential(exercise, request)

login(getCredentialResponse.credential)

Sync Credentials with Digital Asset Hyperlinks

For a very seamless expertise, a consumer’s credentials should sync effortlessly from their different units to their watch, since it’s at present not doable to create credentials on Put on OS.

To allow this, you need to add an entry for Put on OS in your Digital Asset Hyperlinks to affiliate your Put on OS app with different variations of your app. Remember to exactly fill out the asset hyperlink entry, together with your app’s applicationId and the SHA-256 cryptographic hash out of your utility’s digital signature. You possibly can take a look at them out with our app hyperlink verification information.

Furnishing getCredential with built-in credentials

To permit customers to check in with Credential Supervisor, present getCredential with choices for the three built-in authentication varieties: passkeys, passwords, and federated identities like Check in With Google.

// Including choices is a part of creating the credential request
GetCredentialRequest(getCredentialOptions()))

// Furnish checklist of CredentialOptions for the request
droop enjoyable getCredentialOptions(): Checklist<CredentialOption> {
  return listOf(
    // Passkey: Furnish a GetPublicKeyCredentialOption with public key
    // knowledge out of your authentication server
    GetPublicKeyCredentialOption(authServer.getPublicKeyRequestOptions()),
    // Password: Add the supplied GetPasswordOption sort in your checklist
    GetPasswordOption(),
    // Federated Id: Add your required possibility sort (GetGoogleIdOption, under)
    // to orchestrate a token change with the federated id server.
    GetGoogleIdOption.Builder().setServerClientId(SERVER_CLIENT_ID).construct(),
  )
}

When getCredential is known as, Credential Supervisor will use the choices builders present to current customers with a UI to decide on how they need to log in.

Dealing with built-in Credential varieties

After a consumer selects their desired credential within the Credential Supervisor UI, use the results of getCredential (which accommodates the chosen credential) to path to your authentication handlers.

// getCredential returns the chosen credential
login(getCredentialResponse.credential)

// Path to your credential dealing with features to login
droop enjoyable login(credential: Credential): LoginResult {
  when (credential) {
    is PublicKeyCredential -> {
      return authHandler.loginWithPasskey(credential.authenticationResponseJson)
    }
    is PasswordCredential -> {
      return authHandler.loginWithPassword(credential.id, credential.password)
    }
    is CustomCredential -> {
      return authHandler.loginWithCustomCredential(
          credential.sort, credential.knowledge)
    }
    // ‘else’ case, and so on…

The dealing with logic for every of the above loginWith’x’ strategies is barely totally different, though all of them arrange community calls to devoted authentication endpoints. Under are simplified variations of those strategies which show community calls to authenticate customers based mostly on their chosen methodology.

Passkeys require the signed passkey JSON knowledge. Your server will use this knowledge to cryptographically confirm the consumer.

droop enjoyable loginWithPasskey(passkeyResponseJSON: String): LoginResult {
  val validatedPasskey = httpClient.submit(
      "myendpoint/passkey", passkeyResponseJSON, /*different args*/)

  return LoginResult(validatedPasskey)
}

Passwords require community logic to validate the username and password, our instance makes use of subsequent calls to validate the username first. Your backend will validate these in opposition to its consumer database.

droop enjoyable loginWithPassword(userName: String, password: String): LoginResult {
  val validatedUserName = httpClient.submit(
      "myendpoint/username", userName, /*different args*/)
  val validatedPassword = httpClient.submit(
      "myendpoint/password", password, validatedUserName, /*different args*/)

  return LoginResult(ValidatedPassword)
}

Federated identities like Check in with Google require {that a} safe connection is established between your server and your app. Our pattern exhibits a challenge-response circulate initiated from the server, however a shopper generated nonce works as effectively.

Our pattern server gives a problem to our app on request (federatedSessionId, under) which is subsequently used to validate the federated token to authenticate the consumer.

droop enjoyable loginWithCustomCredential(sort: String, knowledge: Bundle): LoginResult {
  if (sort == GoogleIdTokenCredential.TYPE_GOOGLE_ID_TOKEN_CREDENTIAL) {
    token = GoogleIdTokenCredential.createFrom(knowledge).idToken
  }

  // Set up a federated session for along with your server and procure its information
  val federatedSessionId = httpClient.submit("myendpoint/ObtainFederatedSession",
      /*federated backend tackle=*/"https://accounts.google.com")

  // Validate the token with the established federated session.
  val validatedCustomCredential = httpClient.submit(
      "myendpoint/verifyToken", token, federatedSessionID,
      /*federated backend tackle=*/"https://accounts.google.com")

  return LoginResult(validatedCustomCredential)
}

Dealing with secondary Credential varieties

If a consumer faucets dismiss, or swipes again from Credential Supervisor, a GetCredentialCancellationException will probably be thrown for builders to make use of to navigate to their backup login screens, which is able to present secondary authentication choices to customers. These choices are detailed within the Designing Authentication with Credential Supervisor part, above.

// Catch the consumer dismissal
catch (e: GetCredentialCancellationException) {
  // Set off occasion that navigates to ‘BackupLoginScreen’
  uiEvents.ship(UiEvent.NavigateToBackupLogin)
}

Particular Notice: The model of Google Check in that exists exterior of Credential Supervisor is now deprecated and will probably be eliminated, and shouldn’t be supplied as a secondary possibility to keep away from presenting two buttons for a similar objective.

See the Put on OS transition information for extra particulars.

Get began with Credential Supervisor on Put on OS

Implementing Credential Supervisor on Put on OS is an easy course of that delivers important advantages. By adopting this API, you possibly can present your customers with a safe, seamless, and environment friendly technique to authenticate. To start implementation, discover our developer documentation and official pattern app.

To learn the way apps have migrated to Credential Supervisor on Put on OS, take a look at our case research with Todoist, who had been capable of streamline their authentication while reusing their cellular implementation.

For a have a look at how passkeys can enhance login success fee, you possibly can learn all about how X adopted passkeys to attain a safer and user-friendly authentication expertise.

Lastly, you possibly can watch the brand new credential supervisor video weblog on YouTube to strengthen all the pieces you’ve realized right here.

Blissful coding!