Registration

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

If you are using an external identity provider that supports OpenID Connect (OIDC) 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 Authentication section.

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:

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
```
Send your public key, issuer name and key ID to your account representative or to support@sudoplatform.com. 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.
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 support@sudoplatform.com.
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 API Reference and LocalAuthenticationProvider in our GitHub project.
- iOS example: LocalAuthenticationProvider
- Android example: LocalAuthenticationProvider
- TypeScript example: LocalAuthenticationProvider
Invoke registerWithAuthenticationProvider with your AuthenticationProvider implementation as an input.

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 let error {
    // 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:

In Google Play Console, navigate to Release -> Setup -> App signing and copy "SHA-256 certificate fingerprint" of your app.
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:

Log into the Sudo Platform Admin Console. A link and temporary login was emailed to you when your account was activated.
Go to Project Settings and locate the Test Registration Keys section.
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.

For an example approach, please take a look at the open source iOS sample app and the open source Android sample app on Github.

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 let error {
    // 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 let error {
    // 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.
}

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

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.

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

do {
    let uid = try await client.deregister()
} catch let error {
    // 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 client.reset()
} catch let error {
    // 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()

PreviousIntegrate the User SDK NextAuthentication

Last updated 11 months ago

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