Skip to content

Provisioning Passkeys on Behalf of Users - Technical Guide

Table of Contents

  1. Introduction
  2. Prerequisites
  3. Understanding the Provisioning Process
  4. Tenant Configuration
  5. Authentication and Permissions
  6. Step-by-Step Provisioning Guide
  7. Bulk Provisioning
  8. Troubleshooting
  9. Best Practices
  10. Technical Reference

Introduction

This technical guide provides detailed information on using the Crayonic Credential Manager to provision passkeys on behalf of users in any Entra ID tenant. This capability allows administrators to streamline the deployment of passwordless authentication by creating passkeys for users without requiring their direct involvement.

Key Benefits

  • Simplified Deployment: Provision passkeys for multiple users from a central location
  • Reduced User Training: Minimize the need for user training on passkey creation
  • Consistent Configuration: Ensure passkeys are created with the correct settings
  • Flexible Deployment: Works with any Entra ID tenant, not just Crayonic's tenant

Prerequisites

Technical Requirements

  • Windows 10 (1903 or later) or Windows 11
  • .NET Framework 4.8 or later
  • Crayonic Credential Manager application installed
  • Internet connection for Entra ID authentication
  • FIDO2-compatible security key(s)

Administrative Requirements

  • Entra ID tenant
  • Account with one of the following roles:
  • Global Administrator
  • Authentication Administrator
  • Privileged Authentication Administrator
  • Appropriate Microsoft Graph API permissions:
  • User.Read
  • User.ReadBasic.All
  • UserAuthenticationMethod.ReadWrite.All

Security Key Requirements

  • FIDO2-compatible security key
  • Support for resident keys (client-side discoverable credentials)
  • Support for user verification (if required by your security policies)

Understanding the Provisioning Process

How Passkey Provisioning Works

When provisioning passkeys on behalf of users, it's important to understand the underlying process:

  1. Authentication: The administrator authenticates to Entra ID with appropriate permissions
  2. User Selection: The administrator selects the user to provision a passkey for
  3. Passkey Creation: The application initiates the passkey creation process
  4. Security Key Interaction: The security key generates a new credential
  5. Registration: The credential is registered in Entra ID for the selected user
  6. Verification: The application verifies the passkey was successfully created

Technical Flow

The technical flow involves several API calls:

  1. Microsoft Graph API to find and select users
  2. Microsoft Graph API to initiate passkey registration
  3. Windows WebAuthn API for local security key interaction
  4. Microsoft Graph API to complete the registration process

Relying Party Considerations

Passkeys are bound to specific Relying Parties (RPs). For Entra ID applications:

  • Use login.microsoft.com as the RP ID for web applications
  • This ensures the passkey will work with Microsoft 365, Azure Portal, and other Entra ID-integrated web applications

Tenant Configuration

Working with Any Tenant

The Crayonic Credential Manager is designed to work with any Entra ID tenant:

  1. The tenant ID is automatically detected during authentication
  2. All passkey operations are performed in the context of the authenticated tenant
  3. You can switch between tenants by authenticating with different accounts

Multi-Tenant Considerations

If you manage multiple tenants:

  • Ensure you're authenticated to the correct tenant before provisioning passkeys
  • Consider using different security keys for different tenants to avoid confusion
  • Document which passkeys are provisioned in which tenant

Authentication and Permissions

Required Permissions

To provision passkeys on behalf of users, you need:

  1. Entra ID Role: One of the following:
  2. Global Administrator
  3. Authentication Administrator

  4. Privileged Authentication Administrator

  5. Microsoft Graph API Permissions:

  6. User.Read
  7. User.ReadBasic.All
  8. UserAuthenticationMethod.ReadWrite.All

Authentication Methods

The application supports two authentication methods:

  1. Interactive Authentication:
  2. Click "Authenticate with Passkey"
  3. Complete the Microsoft authentication flow

  4. Suitable for ad-hoc provisioning

  5. Non-Interactive Authentication:

  6. Configure environment variables with tenant ID, client ID, and client secret
  7. Application authenticates automatically on startup
  8. Suitable for automated provisioning scenarios

Setting Up Non-Interactive Authentication

For automated scenarios, set the following environment variables:

$env:ENTRA_TENANT_ID = "your-tenant-id"
$env:ENTRA_CLIENT_ID = "your-client-id"
$env:ENTRA_CLIENT_SECRET = "your-client-secret"

You'll need to register an application in Entra ID and grant it the appropriate permissions.

Step-by-Step Provisioning Guide

Preparing for Provisioning

  1. Gather User Information:
  2. User Principal Names (UPNs) of users who need passkeys

  3. Ensure users exist in your Entra ID tenant

  4. Prepare Security Keys:

  5. Ensure security keys are reset or in a state ready for new registrations

  6. Have multiple security keys available if provisioning for multiple users

  7. Launch the Application:

  8. Start Crayonic Credential Manager
  9. Authenticate with an account that has appropriate permissions

Provisioning a Single Passkey

  1. Authenticate to Entra ID:
  2. Click "Authenticate with Passkey"
  3. Complete the authentication process

  4. Verify successful authentication in the status area

  5. Find the User:

  6. Enter the user's UPN in the search field
  7. Click "Search"

  8. Select the user from the dropdown if multiple users are found

  9. Create the Passkey:

  10. Ensure the security key is connected to your computer
  11. Select "login.microsoft.com" as the Relying Party
  12. Click "Create Passkey"
  13. Follow the prompts to interact with the security key

  14. Wait for confirmation of successful registration

  15. Verify the Passkey:

  16. The new passkey should appear in the list of passkeys for the user
  17. Note the credential ID for your records

Handling the Security Key

When interacting with the security key during provisioning:

  1. Connect the security key to your computer
  2. When prompted, touch the security key's sensor
  3. If the security key has a PIN, you may need to enter it
  4. Keep the security key connected until the process completes
  5. Once complete, the security key can be safely removed

Bulk Provisioning

Preparing for Bulk Provisioning

For provisioning passkeys for multiple users:

  1. Create a list of users (UPNs) who need passkeys
  2. Ensure you have enough security keys available
  3. Consider using a tracking system to manage which security key is assigned to which user

Bulk Provisioning Process

  1. Follow the single provisioning steps for each user
  2. Use a consistent naming convention for passkeys to simplify management
  3. Document each provisioning action for audit purposes

Automation Considerations

For larger deployments, consider:

  1. Using the non-interactive authentication method
  2. Creating a PowerShell script to automate the process
  3. Implementing a database to track passkey assignments

Troubleshooting

Common Issues and Solutions

Authentication Issues

Issue: "Insufficient permissions" error during authentication

Solution: Ensure your account has the necessary Entra ID roles and API permissions. Check that the application registration has the required permissions granted and consented.

User Search Issues

Issue: Cannot find user in directory

Solution: Verify the UPN is correct and the user exists in the current tenant. Check that your account has permissions to view user information.

Passkey Creation Issues

Issue: "The operation was canceled by the user" when creating a passkey

Solution: Ensure the security key is properly connected and responsive. Try disconnecting and reconnecting the key, or try a different USB port.

Issue: "We couldn't sign you in" error during passkey creation

Solution: This typically occurs due to a Relying Party (RP) mismatch. Ensure you're using "login.microsoft.com" as the RP for Entra ID applications.

Diagnostic Information

For troubleshooting, check the following log files:

  • Fido2UI_log.txt: General application logs
  • EntraIdAuth_log.txt: Authentication-related logs
  • PasskeyAuth_log.txt: Passkey operation logs

These files are located in the application's installation directory.

Best Practices

Security Considerations

  1. Physical Security:
  2. Maintain physical control of security keys during provisioning

  3. Implement a secure handover process for giving keys to users

  4. Documentation:

  5. Document all provisioning actions for audit purposes

  6. Record which security key is assigned to which user

  7. User Education:

  8. Provide users with information about their new passkey
  9. Explain how to use the passkey for authentication

Operational Considerations

  1. Testing:
  2. Test the provisioning process in a non-production environment first

  3. Verify passkeys work as expected before large-scale deployment

  4. Backup and Recovery:

  5. Consider provisioning multiple passkeys for critical users

  6. Document recovery procedures for lost or damaged security keys

  7. Monitoring:

  8. Regularly audit passkey assignments
  9. Monitor for unused or potentially compromised passkeys

Technical Reference

API Endpoints

The application uses the following Microsoft Graph API endpoints:

  • GET /users: To search for users
  • GET /users/{id}/authentication/fido2Methods: To list existing passkeys
  • POST /users/{id}/authentication/fido2Methods: To initiate passkey creation
  • DELETE /users/{id}/authentication/fido2Methods/{id}: To remove passkeys

WebAuthn Parameters

When creating passkeys, the following WebAuthn parameters are used:

  • Relying Party ID: "login.microsoft.com" for Entra ID applications
  • User Verification: Required (enforces PIN or biometric verification)
  • Attestation: None (attestation information is not collected)
  • Resident Key: Required (creates client-side discoverable credentials)

Error Codes

Common error codes and their meanings:

  • authentication_canceled: User canceled the operation
  • broker_account_not_found: Account selection issue
  • broker_error: Windows Authentication Manager (WAM) broker error
  • insufficient_permissions: Account lacks necessary permissions

© 2025 Crayonic. All rights reserved.