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 Key Registration
  • Test Registration Keys
  • Generate a Test Registration Key
  • De-registration (aka Account Deletion)
  • Resetting Client State
  1. Guides
  2. Users

Registration

PreviousIntegrate the User SDKNextAuthentication

Last updated 28 days ago

In order to access various services in Sudo Platform, you must first register a new user and sign in using the User SDK.

OIDC Federated Sign In

If you are using an external identity provider that supports standard with Sudo Platform then an explicit user registration is not required. An existing user of your identity provider can perform a federated sign in to start using various services provided by Sudo Platform. For more details, please refer to section.

Custom Federated Sign In

The OIDC standard based Federated Sign In is the preferred method to integrate your external identity provider with Sudo Platform however, if you prefer a programmatic method to user sign in, this can be achieved by implementing a Custom Federated Sign In by providing a a signed JWT to the User SDK.

To register a new user based on the custom federated sign in:

  1. Generate a RSA key pair of size 2048 bit. For example, you can use the following OpenSSL commands to generated the required key pair.

    openssl genrsa -out key.pem 2048
    openssl rsa -in key.pem -outform PEM -pubout -out public.pem -RSAPublicKey_out
  2. Send your public key, issuer name and key ID to your account representative or to . The issuer name and key ID is used to uniquely identify the public key that we will use to validate the authentication token generated by you.

  3. Implement AuthenticationProvider and AuthenticationInfo interface defined in the User SDK to issue a signed JWT in the following format:

    // Header
    {
      "alg": "RS256",
      "kid": "<key_id>"
    }
    
    // Payload
    {
      "aud": "identity-service",
      "sub": "<user_id>",
      "jti": "98BCA65D-CAA1-4E91-A23F-FAB819C7C53D",
      "iss": "<issuer_name>",
      "iat": 1608102082,
      "exp": 1608105682 
    }
    // Signature.
    • The digital signature algorithm used to sign the JWT must be RSA with SHA-256 ("RS256").

    • The key ID ("kid") must uniquely match the key ID that you provided in the previous step.

    • The audience ("aud") must always be "identity-service".

    • The subject (“sub”) denotes the unique identifier of the identity being federated. The username of the newly created Sudo Platform user will be set to “sub” contained in the token.

    • The token ID ("jti") should be a unique ID such as UUID.

    • The issuer (“iss”) denotes the issuer of the token, i.e. the external identity provider. This must uniquely match the issuer name that you provided in the previous step.

    • The issued at time ("iss") is milliseconds since epoch representation of when the token was issued.

    • The expiry ("exp") is milliseconds since epoch representation of when the token should expire. This time should be short but long enough to allow for the time it will take for the client to submit the token to Sudo Platform.

    • Optionally any number of custom attributes can be added and if you need those attributes to be persisted in the user record then please contact your account representative or send an email to .

    The string encoded JWT should be returned by toString() (iOS) or encode() (Android and TypeScript) method of AuthenticationInfo with type set to FSSO. For more details, please refer to and LocalAuthenticationProvider in our GitHub project.

    • iOS example:

    • Android example:

    • TypeScript example:

  4. Invoke registerWithAuthenticationProvider with your AuthenticationProvider implementation as an input.

Sign in Key Registration

Sign in key registration is used to create a new user if you don't have users in a registry that supports federated sign in and you want Sudo Platform to manage your users. It uses Apple’s DeviceCheck token or Google Play Integrity token to ensure the registration request is coming from a legitimate device.

During the registration, the client creates a private/public key pair and the public key is stored in the Sudo Platform. The private key is used to digitally sign a token during subsequent sign in and the token is validated using the previously registered public key.

On iOS, to obtain a DeviceCheck token:

// Obtain a DeviceCheck token from iOS via AppDelegate interface.
import DeviceCheck

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
  let currentDevice = DCDevice.current
  if currentDevice.isSupported {
    currentDevice.generateToken(completionHandler: { (data, error) in
      if let error = error {
          // Handle error.
      }

      let deviceCheckToken = data
    })
  }
  return true
}

Complete the iOS registration process by calling the register API:

do {
    let uid = try await client.registerWithDeviceCheck(
        token: deviceCheckToken,
        buildType: "release",
        vendorId: UIDevice.current.identifierForVendor,
        registrationId: UUID().uuidString
    )
} 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 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.
}

On Android, to obtain a Google Play Integrity token:

val integrityTokenProvider: StandardIntegrityTokenProvider = suspendCoroutine { cont ->
            standardIntegrityManager.prepareIntegrityToken(
                PrepareIntegrityTokenRequest.builder()
                    .setCloudProjectNumber(cloudProjectNumber)
                    .build()
            )
                .addOnSuccessListener { tokenProvider ->
                    run {
                        cont.resume(tokenProvider)
                    }
                }
                .addOnFailureListener { exception -> cont.resumeWithException(exception) }
        }

val deviceId = Settings.Secure.getString(
    appContext.contentResolver,
    Settings.Secure.ANDROID_ID
)

val token: StandardIntegrityToken =
    suspendCoroutine { cont ->
        integrityTokenProvider.request(
            StandardIntegrityTokenRequest.builder()
                .setRequestHash(deviceId)
                .build()
        )
            .addOnSuccessListener { token ->
                run {
                    cont.resume(token)
                }
            }
            .addOnFailureListener { exception -> cont.resumeWithException(Exception("$exception")) }
    }

Complete the Android registration process by calling the register API:

CoroutineScope(Dispatchers.IO).launch {
    try {
        client.registerWithGooglePlayIntegrity(
            "<app_package_name>",
            deviceId,
            token.token(),
            UUID.randomUUID().toString()
        )
        // Registration was successful.
    } catch (e: RegisterException) {
        // Handle error. A failure result may be returned if the backend is unable
        // to perform the registration due to availability or security issues.
    }
}

If you have enabled signing certificate validation for Android registrations then you must also complete the following steps:

  1. In Google Play Console, navigate to Release -> Setup -> App signing and copy "SHA-256 certificate fingerprint" of your app.

  2. In Sudo Platform Admin Console, navigate to Overview -> Settings and click on "Add" button to add the signing certificate fingerprint that you copied in the previous step.

The signing certificate fingerprint is owned by the admin user who created it. If the owner is deleted then the fingerprint will also be deleted for security reasons. If the owner is being deleted for off-boarding then make sure a new signing certificate's fingerprint is created by another admin user and re-signed app released before deleting the original owner.

Test Registration Keys

To bypass various security and entitlement restrictions for running integration tests, you can use test registration keys. Use test registration keys when other registration techniques are unavailable, or when writing integration tests.

A test registration key allows you to register a device multiple times. Additionally, you can manipulate the registered user's entitlements so that more resources can be provisioned than what is allowed by default.

Generate a Test Registration Key

Test registration keys can be generated and downloaded in the Admin Console. Keys are specific to the logged-in Admin Console user and the project (e.g. dev, qa, prod). A generated key can only be downloaded once. If you cannot locate a previously generated key, you will need to revoke they key and generate a new one.

To download a test registration key:

  1. Log into the Sudo Platform Admin Console. A link and temporary login was emailed to you when your account was activated.

  2. Go to Project Settings and locate the Test Registration Keys section.

  3. Click on Generate Test Registration Key and follow the prompt to download the newly generated key.

A PEM encoded test registration key can be passed to the test via a number of ways, e.g. via environment variable, temporary file etc. Regardless of the mechanism chosen, keep the key data secure and do not include it in your app build published to end users.

We don't prescribe the method in which to pass the test registration key and key ID as the approach will likely vary depending on whether you are writing integration tests vs setting up CI, etc.

Initialize a TEST authentication provider.

// "testKey" is PEM encoded TEST key obtained from the previous step. "name" parameter should be unique for each test suite.
// "KeyManager" instance should use a unique namesapce as well so resetting it does not cause other keys to be removed.
do {
    let testAuthenticationProvider = try TESTAuthenticationProvider(
        name: "mytest",
        key: testKey,
        keyId: "Key ID of your TEST key from the admin console.",
        keyMananger: SudoKeyManagerImpl(
            serviceName: "com.sudoplatform.appservicename",
            keyTag: "com.sudoplatform",
            namespace: "mytest"
        )
    )
} 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 or basic system resources are 
    // unavailable.
}
// "name" parameter should be unique for each test suite.
// "privateKey" and "keyId" are PEM encoded TEST registration key and key ID obtained from 
// the previous step.
val keyManager = KeyManagerFactory(appContext).createAndroidKeyManager()
// Note: The public key is optional as it can be derived from the private key. However, on
// Android API 23 this is not possible due to limitations in Java security provider so 
// when running tests with Android API 23 emulator generate the public key using
// "openssl rsa -in <private_key> -outform PEM -RSAPublicKey_out" and pass the resulting
// public key as publicKey parameter.
val testAuthenticationProvider = TESTAuthenticationProvider("mytest", privateKey, null, keyManager, keyId)
// "name" parameter should be unique for each test suite.
// "privateKey" and "keyId" are PEM encoded TEST registration key and key ID obtained from 
// the previous step.
const testAuthenticationProvider = new TESTAuthenticationProvider(
  'mytest',
  privateKey,
  keyId,
)

Registering with TEST authentication provider.

do {
    let uid = try await client.registerWithAuthenticationProvider(authenticationProvider: auttestAuthenticationProviderhProvider, registrationId: UUID().uuidString)
} 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.registerWithAuthenticationProvider(
            testAuthenticationProvider,
            UUID.randomUUID().toString()
        )
        // Registration was successful.
    } catch (e: RegisterException) {
        // Handle error. A failure result may be returned if the backend is unable
        // to perform the registration due to availability or security issues.
    }
}
try {
  await client.registerWithAuthenticationProvider(
    testAuthenticationProvider,
    uuid.v4(),
  )
  // Registration was successful.
} catch (err) {
  // Handle error. A failure result may be returned if the backend is unable
  // to perform the registration due to availability or security issues.
}

De-registration (aka Account Deletion)

De-registering the user deletes the user and all associated resources from Sudo Platform.

If you are using federated sign-in and you wish to delete the user do not call the deregister API. Use the appropriate API provided by your identity provider instead.

do {
    let uid = try await client.deregister()
} 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.deregister()
        // User de-registered successfully.
    } catch (e: DeregisterException) {
        // Handle error. A failure result may be returned if the backend is unable
        // to perform the de-registration due to availability or security issues.
    }
}
try {
  await client.deregister()
  // User de-registered successfully.
} catch (err) {
  // Handle error. A failure result may be returned if the backend is unable
  // to perform the de-registration due to availability or security issues.
}

Resetting Client State

You can reset the internal state information maintained by SudoUserClient by calling reset API.

Resetting the client state will cause all persistent data to be lost including sign in key, authentication tokens and username. You would no longer be able to sign in as the previously registered user so a new user must be registered.

do {
    try await client.reset()
} 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 or basic system resources are
    // unavailable.
}
client.reset()
client.reset()

For an example approach, please take a look at the and the on Github.

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

As with most platform APIs, de-registering requires the client to be signed in. Please see section for more details.

🗺️
OpenID Connect (OIDC)
Authentication
support@sudoplatform.com
support@sudoplatform.com
API Reference
LocalAuthenticationProvider
LocalAuthenticationProvider
LocalAuthenticationProvider
open source iOS sample app
open source Android sample app
iOS
Android
Authentication