Skip to main content

Identity Assurance Levels (IAL)

Overview​

In this digital wallet application, users are assigned an Identity Assurance Level (IAL) reflecting the confidence in their verified identity. This level determines the level of access and security required for various interactions within the app. The One37ID SDK manages identity verification and supports multiple IALs, with each level requiring progressively higher verification standards based on identity proofing.

Identity Assurance Levels Explained​

The app uses four primary levels of identity assurance, each associated with different verification requirements and access permissions:

  1. Trust Level 0 (Guest):

    • Description: The default, unverified level where no verified identity is present.
    • Verification Requirements: None.
    • Typical Use Case: Basic, limited access without transaction privileges.

  2. IAL 1 (Basic Assurance):

    • Description: Provides a basic level of assurance in the user's identity.
    • Verification Requirements: Basic contact verification, such as an email or phone number.
    • Typical Use Case: Low-risk interactions that don't involve sensitive data.

  3. IAL 2 (Moderate Assurance):

    • Description: Provides moderate assurance that the user is who they claim to be.
    • Verification Requirements: Requires a government-issued ID and biometric verification.
    • Typical Use Case: Transactions requiring secure verification, such as accessing private data or financial transfers.

  4. IAL 3 (High Assurance):

    • Description: High confidence in the user's identity, suitable for high-security applications.
    • Verification Requirements: In-person verification where users physically present a government-issued ID.
    • Typical Use Case: High-risk transactions or accessing highly confidential information.

Setting the IAL Level of a Wallet​

The wallet’s IAL level is configured by defining a specific set of ialDefinitions within the AgentConfig object. This configuration tells the wallet agent which credentials to consider when assessing the IAL, allowing it to determine the highest IAL among the specified credentials.

Process Overview:​

  1. Define Credential Types for IAL:

    • Agencies or organizations can specify credential types (e.g., email, ID card) in the ialDefinitions list within the AgentConfig. This defines which credentials should contribute to the wallet’s IAL level.
    • Specifying credential types in this configuration allows organizations to prioritize certain verification types, such as verified email or government-issued ID, based on their IAL requirements.

  2. Initialize Agent with IAL Configuration:

    • When initializing the agent, pass this ialDefinitions list within the AgentConfig to instruct the SDK on which credentials to check for IAL determination.

  3. SDK’s Highest IAL Selection Mechanism:

    • When agent.getIAL() is called, the SDK initiates a scan through the wallet’s credentials to identify those matching the specified subset in ialDefinitions.
    • If matching credentials are found, the SDK assigns the IAL based on the highest available IAL among those credentials.
    • If no matching credentials are found or if no definitions are set, the default IAL level is set to IAL 1 if a verified email credential exists.

Explanation of the IAL JSON Configuration​

Here’s a sample ialDefinitions configuration within the AgentConfig, detailing how to map IAL levels to specific credentials:

ialDefinitions: [
  {
    issuerDid: 'did:web:137.dev-one37.id',             // Unique identifier of the credential issuer.
    schemaName: 'com.one37id.email',                   // Specifies the type of credential (e.g., verified email).
    namespace: 'personal.contact.verifiedemail',       // Designates the domain in which this credential applies.
    mapping: [                                         // Maps trust levels to IAL levels based on conditions.
      { condition: 'greaterEquals', trustlevel: 0, ial: IALLevel.IAL1 },
    ],
  },
  {
    issuerDid: 'did:web:137.dev-one37.id',
    schemaName: 'com.one37id.identitycard',
    namespace: 'personal.biographic.identitycard',
    mapping: [
      { condition: 'lessEquals', trustlevel: 0, ial: IALLevel.IAL0 },
      { condition: 'equals', trustlevel: 1, ial: IALLevel.IAL1 },
      { condition: 'equals', trustlevel: 2, ial: IALLevel.IAL2 },
      { condition: 'greaterEquals', trustlevel: 3, ial: IALLevel.IAL3 },
    ],
  },
],

Field Explanations:

  • issuerDid: The decentralized identifier (DID) of the credential issuer, uniquely identifying the organization responsible for verification.
  • schemaName: Specifies the type of credential (e.g., email, identitycard) being validated.
  • namespace: Represents the domain the credential applies to, aiding in classification.
  • mapping: Contains conditions to map trust levels to IAL levels:
    • condition: Defines the relationship (e.g., equals, greaterEquals) between trustlevel and IAL.
    • trustlevel: Required trust level to achieve the specified IAL.
    • ial: Specifies the IAL assigned when the condition is met.

Example of Determining the Highest IAL​

This example demonstrates how the SDK scans designated primary credentials to determine the highest available IAL in the wallet:

const getHighestIAL = async () => {
  const agent = await initializeAgent(); // Pass the config with ialDefinitions
  const ialResult = await agent.getIAL();

  console.log(`Highest IAL determined: ${ialResult.result}`); // Logs the highest IAL level among primary credentials
  return ialResult.result;
};

This code demonstrates how One37ID SDK:

  • Scans through the designated subset of primary credentials in ialDefinitions.
  • Determines and assigns the highest available IAL level based on the credentials present.

Upgrading Identity Assurance Levels​

This wallet application adheres to NIST 800-63 standards for identity proofing and upgrading users to progressively higher IALs. Each step ensures that users provide more rigorous forms of identity verification.

  1. Upgrade from Trust Level 0 to IAL 1:

    • Requirement: Basic contact verification (e.g., email address or phone number).
    • Implementation:
      • Use the SDK’s verification function to send a verification link or code.
      • Upon successful verification, the user’s IAL upgrades to IAL 1.

  2. Upgrade from IAL 1 to IAL 2:

    • Requirement: Verification with a government-issued ID and biometric verification (e.g., facial recognition).
    • Implementation:
      • Prompt the user to upload a government-issued ID and complete a selfie for facial recognition.
      • Upon successful verification, the IAL upgrades to IAL 2.

  3. Upgrade from IAL 2 to IAL 3:

    • Requirement: In-person verification where users physically present a government-issued ID.
    • Implementation:
      • Direct the user to a designated location for physical ID verification.
      • Confirm the process, then upgrade to IAL 3.

Reference: For more on NIST 800-63 identity guidelines, refer to NIST's official documentation.

Primary Credential and IAL Management​

The primary credential is crucial in determining the wallet’s IAL level:

  1. Defining the Primary Credential:

    • The home agency designates one credential as primary, influencing the wallet’s IAL. Examples include National ID or Employment Badge.
    • If multiple credentials share the highest IAL level, the system selects the first credential of the highest IAL as primary.

  2. Automatic IAL Updates:

    • When a primary credential with a higher IAL is issued, the wallet’s IAL updates to match.
    • For credentials without the primary flag, the wallet’s IAL remains unchanged.

  3. Fallback Mechanism for Revocation:

    • If the primary credential is missing, revoked, or invalid, the system reverts to the next highest available credential, and the user is notified of the change.
X

Graph View