Internet Identity

The Test OpenID provider is a throwaway OpenID Connect (OIDC) identity provider (similar to Okta or OneLogin) designed to test Internet Identity's (II) OpenID and SSO sign-in flows. It is built on node-oidc-provider and provides the necessary endpoints for II's two-hop SSO discovery process.

Warning: This is for test/dev only. It uses in-memory storage, dev signing keys, hardcoded credentials, and sets Access-Control-Allow-Origin: *. Never use this as a real Identity Provider.

Supported Endpoints

The principal used for a per-app delegation is derived from the target_origin. To ensure correct derivation, follow these rules:

1. Use Bare Origins: Pass a bare https://<host> (e.g., https://example.com). Do not include paths, ports, or trailing slashes. Non-bare origins bypass internal remapping and derive different principals.
2. Gateway Remapping: II automatically folds *.icp0.io and *.icp.net gateway origins to the legacy *.ic0.app origin to ensure stable principals.
3. Custom Derivation Origins: Some applications use a custom derivation origin declared via /.well-known/ii-alternative-origins (e.g., app.example.com might derive principals as <canister>.ic0.app).

Troubleshooting Principal Mismatches: If mcp_get_accounts returns an empty set or the user's balance appears incorrect, the application is likely using a custom derivation origin. To resolve this, fetch the app's ii-alternative-origins and use that declared origin as the target_origin in your MCP calls.

Internet Identity uses a two-hop discovery mechanism to resolve SSO providers. The flow works as follows:

1. Hop 1: The domain resolves /.well-known/ii-openid-configuration to obtain the client_id, the openid_configuration URL, and the provider name.
2. Hop 2: II uses the openid_configuration URL to fetch standard OIDC discovery data (issuer, jwks_uri, authorization_endpoint).
3. Verification: II fetches keys from the jwks_uri to verify the ID token.

Security Constraints: During verification, the canister cross-checks the ID token:

• aud must match the discovered client_id.
• iss must match the discovered issuer.
• The issuer host must match the openid_configuration host.
• The authorization_endpoint must share the issuer's host.

The browser uses response_type=code id_token and response_mode=form_post, posting the result to the II origin's /callback.

Issuing a credential is a two-step process designed to allow for authenticated state transfer and asynchronous signing (e.g., using canister signatures).

1. Prepare Credential (prepare_credential)

The issuer validates the signed_id_alias.credential_jws to ensure the user has a valid has_id_alias principal and that the credential_spec is applicable to the caller.

If valid, the issuer returns PreparedCredentialData.prepared_context. This context is an opaque blob used to transfer information between the preparation and issuance steps. For example, it might contain a timestamped, unsigned version of the VC.

2. Get Credential (get_credential)

This is a query call. The caller must provide the same parameters as the preparation step, plus the prepared_context returned previously. The issuer verifies that the context is consistent with the request and returns the final signed credential in JWS format (vc_jws).

Security Note: Both calls must be authenticated; the caller's principal must match the principal for which the credential is being requested.

// Step 1: Prepare
type PrepareCredentialRequest = record {
    signed_id_alias : SignedIdAlias;
    credential_spec : CredentialSpec;
};
type PreparedCredentialData = record { prepared_context : opt vec nat8 };

// Step 2: Get (Query)
type GetCredentialRequest = record {
    signed_id_alias : SignedIdAlias;
    credential_spec : CredentialSpec;
    prepared_context : opt blob;
};
type IssuedCredentialData = record { vc_jws : text };

To allow a client application to act on behalf of a user without requiring constant interaction with a security device, Internet Identity uses delegation chains.

The Delegation Flow

1. Authentication: The user authenticates via a security device.
2. Session Key: The client application uses a session key (e.g., Ed25519 or ECDSA).
3. Client Delegation: The Internet Identity Service canister creates a delegation from the user's main identity to the session key. This delegation is:
   • Unscoped: Valid for all canisters.
   • Lifetime: Has a maximum lifetime of 30 days (defaulting to 30 minutes).
   • Signed: Uses a canister signature.
4. Identity Frontend Delegation: The Internet Identity frontend also manages a delegation from the security device's public key to a session key managed by the frontend, allowing it to interact with the backend without re-invoking the security device for every signature.

This allows the session key to sign for the user's main identity for a specified duration.