Authenticating in Auth0 with Keyless

Integrating the Keyless authentication mechanism with existing IAMs requires some preliminary work on various parts of the customer’s Service Provider:

• Binding of the user’s Auth0 identity with a Keyless ID: this happens via Keyless Enrollment. The user performs a normal enrollment with an option in the configuration that accepts an idToken, coming from Auth0. This can be retrieved via standard Auth0 login flow.

• Account linking: After the user’s idToken has been bound to a Keyless Identity, the Auth0 authentication with Keyless will succeed. This authentication, though, returns a different user_id. This is because the Auth0 user_id and the Keyless user_id have not been linked. There are many tutorials on how to perform Account Linking in Auth0 tenants

Configure Enterprise OIDC Connection to Keyless in Auth0

Create a secure connection between Keyless and Auth0, allowing you to leverage Keyless as an Identity Provider in Auth0.

Before following this guide, contact the Keyless Delivery Team to get the following information:

• Discovery URL: https://idp.keyless.io/realms/YOUR_REALM/.well-known/openid-configuration

• Client ID: Will be provided by Keyless Delivery team.

• Client Secret: Will be provided by Keyless Delivery team.

• Scopes: Include any additional scopes you want to request (e.g., openid, profile, email).

Step 1: Create a Connection in Auth0

1. Log in to your Auth0 account and navigate to the Dashboard.

2. In the Dashboard, go to Authentication > Enterprise > OpenID Connect.

3. Click Create Connection

   • Name: Enter a name for your connection (e.g., Keyless-SDK-Connection).

   • Issuer URL: Enter the Discovery URL provided by the Delivery team

4. Test the Connection by logging in with a test user and navigating to the Try Connection option in the Auth0 Dashboard.

Step 2: Enable the Connection for Applications

1. In the Auth0 Dashboard, go to Applications > Applications.

2. Select the application you want to connect to Keyless, navigate to the Connections tab, and enable the newly created Keyless connection.

Once everything has been set up, specify the name of the Auth0 connection you’ve just created as part of the /authorize endpoint of Auth0 within the SDK configuration.

Step 3: Link Keyless accounts to Auth0 accounts

This step can vary considerably by implementation. Contact the Keyless Solution Engineering team to discuss the best approach for your setup.

Mobile Integration

Before performing Enrollment and Authentication, follow the mobile SDK guide to using the Keyless SDK.

Enrollment

To enroll a user,

1. Retrieve the id_token from Auth0

2. Perform a Keyless Enrollment, providing the id_token into the withIAMToken builder function:

Android

val idToken = ... // retrieve your id_token from Auth0

val configuration = EnrollmentConfiguration.builder
.withIAMToken(token = idToken)
.build()

Keyless.enroll(
enrollmentConfiguration = configuration,
onCompletion = { result ->
    when (result) {
        is Keyless.KeylessResult.Success -> Log.d("KeylessSDK ", "Enroll success - userId ${result.value.keylessId}")
        is Keyless.KeylessResult.Failure -> Log.d("KeylessSDK ", "Enroll failure - error code ${result.error.code}")
    }
}
)

iOS

let idToken = // retrieve your id_token from Auth0
let configuration = Keyless.EnrollmentConfiguration.builder
    .withIAMToken(token: idToken)
    .build()

Keyless.enroll(enrollmentConfiguration: configuration) { result in
    switch result {
    case .success(let success):
        print("Enroll success - userID \(success.keylessId)")
    case .failure(let failure):
        print("Enroll failed - error \(failure.message)")
    }
}

Flutter

import 'package:keyless_flutter_sdk/keyless.dart';
import 'package:keyless_flutter_sdk/models/configurations/enrollment_configuration.dart';

// retrieve your id_token from Auth0
final idToken = "..."; 

final configuration = BiomEnrollConfig(iamToken: idToken);

try {
    final result = await Keyless.instance.enroll(configuration);
    print("Enrollment successful. KeylessID: ${result.keylessId}");
} catch (error) {
    print("Enrollment failed: $error");
}

Once the Enrollment phase completes successfully, authenticate the user.

Authentication

Two preliminary steps are necessary before authentication:

• Generatie a cryptographically secure UUID that we’re going to call operationId

• Retrieve a value called keylessId via the getUserId() API.

1. Concatenate the UUID and keylessId to produce the login_hint: login_hint = <operation_id>;<keyless_id>

2. Authenticate with Keyless providing the operationId:

Android

val configuration = AuthenticationConfiguration.builder
val operationId = UUID.randomUUID().toString()
val configuration = AuthenticationConfiguration.builder
  .withOperationInfo(operationId = operationId)
  .build()

Keyless.authenticate(
    authenticationConfiguration = configuration,
    onCompletion = { result ->
        when (result) {
          is Keyless.KeylessResult.Success -> {
            Log.d("KeylessSDK ", "Authentication success")
            val keylessId = ... // get from Keyless.getUserId() in case of success
            val loginHint = "$operationId;$keylessId"
            // After having generated the `loginHint`, you can start your
            // normal Auth0 flow with the Keyless connection and passing
            // the loginHint above
          }
          is Keyless.KeylessResult.Failure -> {
            Log.d("KeylessSDK ", "Authentication failure - error code ${result.error.code}")
          }
       }
    }
)

iOS

let operationID = UUID().uuidString // or some other true random generation method
let configuration = Keyless.AuthenticationConfiguration.builder
    .withOperationInfo(id: operationID)
    .build()

Keyless.authenticate(authenticationConfiguration: configuration) { result in
    switch result {
    case .success(let success):
        let loginHint = "\(operationID);\(Keyless.getUserId())"
        // After having generated the `loginHint`, you can start your
        // normal Auth0 flow with the Keyless connection and passing
        // the loginHint above
    case .failure(let error):
        print("Failed authentication, cannot start Auth0 login flow.")
    }
}

Flutter

import 'package:keyless_flutter_sdk/keyless.dart';
import 'package:keyless_flutter_sdk/models/configurations/authentication_configuration.dart';
import 'package:uuid/uuid.dart';

// Generate a cryptographically secure UUID
final operationId = Uuid().v4();

final configuration = BiomAuthConfig(operationId: operationId);

try {
    final result = await Keyless.instance.authenticate(configuration);
    // Get the keylessId after successful authentication
    final keylessId = await Keyless.instance.getUserId();
    final loginHint = "$operationId;$keylessId";
    
    // After having generated the `loginHint`, you can start your
    // normal Auth0 flow with the Keyless connection and passing
    // the loginHint above
    print("Authentication successful. Login hint: $loginHint");
} catch (error) {
    print("Authentication failed: $error");
}

Once successfully authenticated, launch a custom tab to log in with Keyless via Auth0, providing the login_hint previously built as a parameter with key login_hint.

OpenID URL Configuration

Once you’re given access to the Keyless Dashboard by our tech support team, configure the OpenID URL in the Keyless Dashboard, o

1. Open the Access Control page.

2. Click on the IDP Configuration tab, this will redirect you to another page which contains what we’re looking for, the OpenID Configuration.

3. Set the OpenID Configuration URL please type a valid OpenID URL, here some examples of valid URLs:

   • https://yourdomain.auth0.com/.well-known/

   • https://yourdomain.auth0.com/.well-known

   • https://yourdomain.auth0.com/

   • https://yourdomain.auth0.com

4. Click the Save Configuration button.