Device Code Authentication

The Device Code authentication flow is designed for input-constrained devices and applications where a user cannot easily enter credentials directly. It allows users to authenticate using a separate web browser or device.

            This authentication flow is ideal for scenarios like smart TVs, IoT devices, or command-line interfaces where interactive sign-in is not feasible.
        

How it Works

The Device Code flow operates as follows:

The application requests a device code from the Azure Identity provider.
The identity provider returns a user code (e.g., "A1B2-C3D4") and a verification URL.
The application displays the user code and the verification URL to the user.
The user navigates to the verification URL on a separate device (e.g., a smartphone or computer) and enters the user code.
The user then signs in to their Azure account via the verification URL.
Once authentication is successful, the identity provider issues an access token back to the application.

API Reference

Initiate Device Code Flow

This endpoint initiates the device code authentication process.

Request

POST /oauth2/v2.0/devicecode

Parameters

Name	Description	Required
client_id	The client ID of your application.	Yes
scope	The scopes your application requires (e.g., `https://graph.microsoft.com/.default`).	Yes
tenant	(Optional) The Azure AD tenant ID or domain. Defaults to common.	No

Response (Example)


{
  "device_code": "aGVsbG8gdGhlcmU=",
  "user_code": "ABCD-EFGH",
  "verification_url": "https://microsoft.com/devicelogin",
  "expires_in": 1800,
  "interval": 5,
  "message": "To sign in, use a web browser to open the page https://microsoft.com/devicelogin and enter the code ABCD-EFGH to authenticate."
}

Key Fields:

device_code: A secret code used by the client to poll for an access token.
user_code: The code displayed to the user for entry on the verification URL.
verification_url: The URL the user needs to visit to authenticate.
expires_in: The lifetime in seconds of the device_code.
interval: The minimum number of seconds the client should wait between polling for an access token.

Poll for Access Token

After initiating the flow, your application should poll this endpoint to check if the user has completed the authentication on the verification URL.

Request

POST /oauth2/v2.0/token

Parameters

Name	Description	Required
grant_type	Must be set to `urn:ietf:params:oauth:grant-type:device_code`.	Yes
client_id	The client ID of your application.	Yes
device_code	The `device_code` obtained from the initial device code request.	Yes

Response (Success Example)


{
  "token_type": "Bearer",
  "scope": "https://graph.microsoft.com/.default",
  "expires_in": 3600,
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  "refresh_token": "rT5N...tU"
}

Response (Pending Example)


{
  "error": "authorization_pending"
}

Response (Exceeded Device Code Lifetime Example)


{
  "error": "expired_token"
}

The client should continue polling until it receives an access token or an error indicating the code has expired or been cancelled.

Client Implementation Notes

Handle the authorization_pending response by waiting the specified interval before polling again.
Implement retry logic with exponential backoff for transient network errors.
Be aware of the expires_in value for the device code and inform the user if they take too long.
Securely store the obtained access_token and refresh_token.

Security Consideration: Ensure your application handles the device_code and subsequent token requests securely. Do not expose sensitive information in client-side code.

Example Usage (Conceptual)

Python (using a hypothetical library)


from azure_identity import DeviceCodeCredential
import asyncio

async def main():
    credential = DeviceCodeCredential()
    token = await credential.get_token("https://graph.microsoft.com/.default")
    print(f"Access Token: {token.token}")

if __name__ == "__main__":
    asyncio.run(main())