LogoLogo
  • Platform Overview
  • 🗺️Guides
    • Getting Started
    • Users
      • Integrate the User SDK
      • Registration
      • Authentication
      • SDK Releases
      • API Reference
    • Entitlements
      • Administrative API
        • Integrating the Administrative API
        • Entitlement Definitions
        • Managing Entitlements Sets
        • Managing Entitlements Sequences
        • Managing User Entitlements
        • API Schema
      • End-user API
        • Integrate the Entitlements SDK
        • Redeeming Entitlements
        • Retrieving Entitlements
        • SDK Releases
        • API Reference
    • Sudos
      • Integrate the Sudo Profiles SDK
      • Sudo Entitlements
      • Manage Sudos
      • SDK Releases
      • API Reference
    • Telephony
      • Integrate the Telephony SDK
      • Manage Phone Numbers
      • Text Messaging
      • Voice Calling
      • Telephony Simulator
      • SDK Releases
      • API Reference
    • Email
      • Integrate the Email SDK
      • Email Entitlements
      • Manage Email Addresses
      • Sending & Receiving Email
      • Manage Email Folders
      • Draft Email Messages
      • Manage Email Address Blocklists
      • Email Address Public Information
      • Pagination
      • Caching
      • Configuration Data
      • Email Notifications
      • SDK Releases
      • API Reference
    • Decentralized Identity
      • Edge Agent
        • Relay SDK
          • Integrate the Relay SDK
          • Relay Entitlements
          • Manage Relay Postboxes
          • Manage Relay Messages
          • Receiving Messages
          • SDK Releases
        • Edge Agent SDK
          • Integrate the Edge Agent SDK
          • Agent Management
          • Manage Wallets
          • Establishing Connections
          • Manage Connections
          • Messaging
          • Manage DIDs
          • Accepting New Credentials
          • Manage Credentials
          • Present Credentials for Verification
          • Utilize Alternative Cryptography Providers
          • SDK Releases
          • Standards and Protocols
      • Cloud Agent
        • Cloud Agent Admin API
          • Integrate the Cloud Agent Admin API
          • Aries Interop Profile (AIP)
            • Connection Exchanges
            • Credential Exchanges
            • Proof Exchanges
          • Connections
          • Basic Messages
          • Credentials
            • Anoncreds Credentials
              • Schemas
              • Credential Definitions
            • W3C Credentials
          • Audit Logs
          • API Schema
          • Error Codes
          • Standards and Protocols
    • Virtual Cards
      • Integrate the Virtual Cards SDK
      • Virtual Cards Entitlements
      • Virtual Cards Transaction Velocity Constraints
      • Key Management
      • Manage Funding Sources
      • Manage Virtual Cards
      • Manage Transactions
      • Configuration Data
      • Pagination
      • Caching
      • SDK Releases
      • API Reference
    • Virtual Cards Simulator
      • Integrate the Virtual Cards Simulator SDK
      • Simulate Authorizations
      • Simulate Debits
      • Simulate Refunds
      • Simulate Reversals
      • Merchants and Currencies
      • SDK Releases
      • API Reference
    • Virtual Private Network
      • Integrate the VPN SDK
      • VPN Entitlements
      • Manage Servers
      • Manage Connection
      • Observe VPN Related Events
      • SDK Releases
      • API Reference
      • Frequently Asked Questions
    • Secure ID Verification
      • Integrate the Secure ID Verification SDK
      • List Supported Countries
      • Verify an Identity
      • Check Secure ID Verification Status
      • Use the Secure ID Verification Simulator
      • SDK Releases
      • API Reference
    • Password Manager
      • Integrate the Password Manager SDK
      • Accessing the Password Manager
      • Managing Password Vaults
      • Managing Password Vault Items
      • Vault Import and Export
      • Password Utilities
      • Password Manager Entitlements
      • Password Vault Security
      • SDK Releases
      • API Reference
    • Ad/Tracker Blocker
      • Integrate the Ad/Tracker Blocker SDK
      • Manage Rulesets
      • Blocking Ads and Trackers
      • Manage Exceptions
      • SDK Releases
      • API Reference
    • Site Reputation
      • Integrate the Site Reputation SDK
      • Use the Site Reputation SDK
      • SDK Releases
      • API Reference
  • 💡Concepts
    • Sudo Digital Identities
  • 🧱Development
    • Versioning
  • 🏢Administration
    • Admin Console Roles
  • ❓Get Help
    • Request a Demo
    • Report an Issue
Powered by GitBook
On this page
  • OIDC Federated Sign In
  • Custom Federated Sign In
  • Sign In via Private Key
  • Refreshing ID and Access Tokens
  • Sign Out
  1. Guides
  2. Users

Authentication

PreviousRegistrationNextSDK Releases

Last updated 28 days ago

The Sudo Platform allows users to sign in from client apps using various mechanisms. Once signed in, a user obtains authentication tokens (OpenID Connect ID and access tokens) that can be used to access other services within the platform.

OIDC Federated Sign In

In order to use federated sign in, you must have completed the federated sign in setup for your project by contacting .

If you are using an external identity provider that supports standard then Sudo Platform access can be granted via federated sign in. When the user signs into your identity provider they will be federated and authenticated into Sudo Platform via OpenID Connect web flow. The user is not required to sign into your identity provider again until the refresh token expires. The refresh token lifetime can be configured by contacting .

The federated sign in requires the app to be configured with a URL scheme so that the authentication tokens from your identity provider can be passed into your app when the user performs federated sign in via a web view launched by the app. The URL scheme that you set up for your app must match one of the callback and logout URLs configured in the federated sign in configuration. To setup these URLs, contact .

If you have more than one URL scheme configured for callback and logout URLs then make sure you edit "sudoplatformconfig.json" file to keep only the URL scheme that's relevant for your app for "signInRedirectUri" and "signOutRedirectUri".

Setting up a URL scheme for iOS app:

For example, add the following entry in Info.plist file of your app.

    <key>CFBundleURLTypes</key>
    <array>
        <dict>
            <key>CFBundleURLSchemes</key>
            <array>
                <string>$(PRODUCT_BUNDLE_IDENTIFIER)</string>
            </array>
        </dict>
    </array>

Setting up a URL scheme for Android app:

For example, add the following to your app manifest in the main activity section:

<intent-filter>
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />
    <data android:scheme="com.mycompany.myapp"/>
</intent-filter>

Signing in via federated sign in.

do {
    let tokens = try await client.presentFederatedSignInUI(presentationAnchor: window)
    // "tokens.idToken" can be used to initialize other service specific clients to authenticate to the backend API.
    // ID token and access token will expire after number of seconds specified in "lifetime".  The tokens will be
    // refreshed automatically or can be manually refreshed by calling the "refreshTokens" API.
} catch {
    // Handle error. An error may be thrown if the backend is unable to perform
    // requested operation due to availability or security issues.
    // An error might be also be thrown for unrecoverable circumstances arising
    // from programmatic error or configuration error. For example, if the keychain
    // access entitlement is not set up correctly or basic system resources are
    // unavailable.
}
// Your main activity must pass the authentication tokens from your
// identity provider into SudoUserClient when the activity is resumed
// via the URL scheme.
override fun onResume() {
    super.onResume()

    val data = this.intent.data
    if (data != null) {
        client.processFederatedSignInTokens(data)
    }
}

// Present the federated sign in UI assuming it's being called from
// an activity.
client.presentFederatedSignInUI(this) { result ->
    when (result) {
        is ApiResult.Success -> {
            // User registered and signed in successfully.        
        }
        is ApiResult.Failure -> {
            // Handle error. A failure result may be returned if the backend is unable
            // perform the registration due to availability or security issues.
        }
    }
}
try {
  client.presentFederatedSignInUI()
  // User registered and signed in successfully.
catch (err) {
  // Handle error. A failure result may be returned if the backend is unable
  // perform the registration due to availability or security issues.
}

// In addition to the above, you will need to add code to process the redirect url.
processRedirectUrl = async () => {
  const redirectUrl = window.location.href
  await client.processFederatedSignInTokens(redirectUrl)
}

Custom Federated Sign In

Sign In via Private Key

To sign-in using private key based authentication:

do {
    let tokens = try await client.signInWithKey()
    // "tokens.idToken" can be used to initialize other service specific clients to authenticate to the backend API.
    // ID token and access token will expire after number of seconds specified in "lifetime" so use "refreshToken"
    // to refresh these tokens via "refreshTokens" API.
} catch {
    // Handle error. An error may be thrown if the backend is unable to perform
    // requested operation due to availability or security issues.
    // An error might be also be thrown for unrecoverable circumstances arising
    // from programmatic error or configuration error. For example, if the keychain
    // access entitlement is not set up correctly or basic system resources are
    // unavailable.
}
CoroutineScope(Dispatchers.IO).launch {
    try {
        val result = client.signInWithKey()
        // "idToken" can be used to initialize other service specific clients to authenticate to the backend API.
        // ID token and access token will expire after number of seconds specified in "lifetime" so use "refreshToken"
        // to refresh these tokens via "refreshTokens" API.
        println("idToken: ${result.idToken}, accessToken: ${result.accessToken}, refreshToken: ${result.refreshToken}")
    } catch (e: AuthenticationException) {
        // Handle error. A failure result may be returned if the backend is unable
        // to perform the sign in due to availability or security issues.
        println("${e.localizedMessage}")
    }
}

Refreshing ID and Access Tokens

Authentication tokens will expire after 1 hour so in order to avoid needing to sign in periodically you should refresh those tokens.

Each Sudo Platform client such as Telephony client will automatically refresh ID and access tokens as needed but this will incur a delay in the API call so it is recommended to refresh the tokens at a scheduled interval or on app launch.

To refresh ID and access tokens:

do {
    let tokens = try await client.refreshTokens(refreshToken: refreshToken)
    // "tokens.idToken" can be used to initialize other service specific clients to authenticate to the backend API.
    // ID token and access token will expire after number of seconds specified in "lifetime" so use "refreshToken"
    // to refresh these tokens via "refreshTokens" API.
} catch {
    // Handle error. An error may be thrown if the backend is unable to perform
    // requested operation due to availability or security issues.
    // An error might be also be thrown for unrecoverable circumstances arising
    // from programmatic error or configuration error. For example, if the keychain
    // access entitlement is not set up correctly or basic system resources are
    // unavailable.
}
CoroutineScope(Dispatchers.IO).launch {
    try {
        val result = client.refreshTokens(refreshToken)
        // "idToken" can be used to initialize other service specific clients to authenticate to the backend API.
        // ID token and access token will expire after number of seconds specified in "lifetime" so use "refreshToken"
        // to refresh these tokens via "refreshTokens" API.
        println("idToken: ${result.idToken}, accessToken: ${result.accessToken}, refreshToken: ${result.refreshToken}")
    } catch (e: AuthenticationException) {
        // Handle error. A failure result may be returned if the backend is unable
        // to perform the sign in due to availability or security issues.
        println("${e.localizedMessage}")
    }
}
try {
  const result = await client.refreshTokens(refreshToken)
  // "idToken" can be used to initialize other service specific clients to authenticate to the backend API.
  // ID token and access token will expire at the time indicated in tokenExpiry so use "refreshToken"
  // to refresh these tokens via the "refreshTokens" API.
} catch (err) {
  // Handle error. A failure result may be returned if the backend is unable
  // to perform the sign in due to availability or security issues.
}

It is not necessary to perform the sign in again until the refresh token expires as long as the ID token is getting refreshed via the mechanisms mentioned above. It is the consumer's responsibility to perform the sign in at a fixed interval or reactively when notAuthorized error is returned from a platform service client API call. The default expiry for refresh token is 30 days.

Sign Out

To sign out a user:

do {
    try await client.globalSignOut()
} catch {
    // Handle error. An error may be thrown if the backend is unable to perform
    // requested operation due to availability or security issues.
    // An error might be also be thrown for unrecoverable circumstances arising
    // from programmatic error or configuration error. For example, if the keychain
    // access entitlement is not set up correctly or basic system resources are
    // unavailable.
}
CoroutineScope(Dispatchers.IO).launch {
    try {
        client.globalSignOut()
        // Sign out successful.
    } catch (e: SignOutException) {
        // Handle error. A failure result may be returned if the backend is unable
        // perform the sign out due to availability or security issues.
        println("${e.localizedMessage}")
    }
}
try {
  await client.globalSignOut()
  // Sign out successful.  
} catch (err) {
  // Handle error. A failure result may be returned if the backend is unable
  // to perform the sign out due to availability or security issues.     
}

Sign out will invalidate authentication tokens from all devices regardless of the sign in method used. For the current device, all tokens will be invalidated immediately but on other devices the API access will still be granted to up to the lifetime of ID token. The ID token lifetime is 1 hour by default but this can be changed by submitting a support request.

To invalidate authentication tokens for a single device.

do {
    try client.signOut()
} catch {
    // Handle error. An error might be thrown for unrecoverable circumstances arising
    // from programmatic error or configuration error. For example, if the keychain
    // access entitlement is not set up correctly, the client is not signed in,
    // or basic system resources are unavailable.
}
client.clearAuthTokens()
client.clearAuthenticationTokens()

Sign out from hosted UI for OIDC federated sign in.

do {
    try await client.presentFederatedSignOutUI(presentationAnchor: window)
} catch {
    // Handle error. An error may be thrown if the backend is unable to perform
    // requested operation due to availability or security issues.
    // An error might be also be thrown for unrecoverable circumstances arising
    // from programmatic error or configuration error. For example, if the keychain
    // access entitlement is not set up correctly or basic system resources are
    // unavailable.
}
client.presentFederatedSignOutUI { result ->
    when (result) {
        is ApiResult.Success -> {
            // User signed out successfully.        
        }
        is ApiResult.Failure -> {
            // Handle error. A failure result may be returned if the backend is unable
            // perform the sign out due to availability or security issues.
        }
    }
}
client.presentSignOutUI()

This will invalidated any cached information from the web session used to contact Sudo Platform but does not invalidate any authentication tokens. You can call clearAuthTokens or globalSignOut subsequently to either invalidate authentication tokens from the current device or sign out the user from all devices.

See it in action. Be sure to take a look at the and sample apps on GitHub, which demonstrate how to use federated sign in.

In order to use custom federated sign in, you must have completed the custom federated sign in setup described in the section.

In order to sign in using a custom authentication provider, you must invoke signInWithAuthenticationProvider API of SudoUserClient with your AuthenticationProvider implementation as an input similar to how registerWithAuthenticationProvider was invoked to register a new Sudo Platform user. For details of AuthenticationProvider implementation, please refer to the section and .

If a user was registered using , they can use the private key from the public/private key pair generated at registration time to digitally sign an authentication token to sign-in.

🗺️
iOS
Android
support@sudoplatform.com
OpenID Connect (OIDC)
support@sudoplatform.com
support@sudoplatform.com
API Reference
https://developer.apple.com/documentation/uikit/inter-process:communication/allowing:apps:and:websites:to:link:to:your:content/defining:a:custom:url:scheme:for:your:appdeveloper.apple.com
Registration
Registration
Sign in Key Registration
Create Deep Links to App Content  |  Android DevelopersAndroid Developers
Logo