Azure AAD: OAuth 2.0 device code flow implementation (#301)

Author: Francesco Cogno

azure_sdk_auth_aad/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name               = "azure_sdk_auth_aad"
-version            = "0.45.0"
+version            = "0.45.1"
 description        = "Rust wrappers around Microsoft Azure REST APIs - Azure OAuth2 helper crate"
 readme             = "README.md"
 authors            = ["Francesco Cogno <francesco.cogno@outlook.com>"]
@@ -18,17 +18,20 @@ edition            = "2018"
 azure_sdk_core       = { path = "../azure_sdk_core", version = "0.43.3" }
 oauth2               = { version = "3.0.0-alpha.9", features = ["reqwest-010", "futures-03"], default-features = false}
 url                  = "2.1"
-failure              = "0.1"
 futures              = "0.3"
 serde                = "1.0"
 serde_derive         = "1.0"
 chrono               = "0.4"
 serde_json           = "1.0"
 log                  = "0.4"
 reqwest              = { version = "0.10", features = ["json"] }
+async-timer          = { version = "1.0.0-beta.3" }
+thiserror	     = "1.0"
 
 [dev-dependencies]
-tokio                = { version = "0.2", features = ["macros"] }
+tokio                  = { version = "0.2", features = ["macros"] }
+azure_sdk_storage_core = { version = "0.44" }
+azure_sdk_storage_blob = { version = "0.44" }
 
 [features]
 test_e2e             = []

azure_sdk_auth_aad/examples/device_code_flow.rs

@@ -0,0 +1,90 @@
+use azure_sdk_auth_aad::*;
+use azure_sdk_storage_blob::prelude::*;
+use azure_sdk_storage_core::prelude::*;
+use futures::stream::StreamExt;
+use oauth2::ClientId;
+use std::env;
+use std::error::Error;
+use std::sync::Arc;
+
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn Error>> {
+    let client_id =
+        ClientId::new(env::var("CLIENT_ID").expect("Missing CLIENT_ID environment variable."));
+    let tenant_id = env::var("TENANT_ID").expect("Missing TENANT_ID environment variable.");
+
+    let storage_account_name = std::env::args()
+        .nth(1)
+        .expect("please specify the storage account name as first command line parameter");
+
+    let client = Arc::new(reqwest::Client::new());
+
+    // the process requires two steps. The first is to ask for
+    // the code to show to the user. This is done with the following
+    // function. Notice you can pass as many scopes as you want.
+    // Since we are asking for the "offline_access" scope we will
+    // receive the refresh token as well.
+    // We are requesting access to the storage account passed as parameter.
+    let device_code_flow = begin_authorize_device_code_flow(
+        client.clone(),
+        &tenant_id,
+        &client_id,
+        &[
+            &format!(
+                "https://{}.blob.core.windows.net/.default",
+                storage_account_name
+            ),
+            "offline_access",
+        ],
+    )
+    .await?;
+
+    // now we must show the user the authentication message. It
+    // will point the user to the login page and show the code
+    // they have to specify.
+    println!("{}", device_code_flow.message());
+
+    // now we poll the auth endpoint until the user
+    // completes the authentication. The following stream can
+    // return, besides errors, a success meaning either
+    // Success or Pending. The loop will continue until we
+    // get either a Success or an error.
+    let mut stream = Box::pin(device_code_flow.stream());
+    let mut authorization = None;
+    while let Some(resp) = stream.next().await {
+        println!("{:?}", resp);
+
+        // if we have the authorization, let's store it for later use.
+        if let DeviceCodeResponse::AuthorizationSucceded(auth) = resp? {
+            authorization = Some(auth);
+        }
+    }
+
+    // remove the option (this is safe since we
+    // unwrapped the errors before).
+    let authorization = authorization.unwrap();
+
+    println!(
+        "\nReceived valid bearer token: {}",
+        &authorization.access_token.secret()
+    );
+
+    if let Some(refresh_token) = authorization.refresh_token.as_ref() {
+        println!("Received valid refresh token: {}", &refresh_token.secret());
+    }
+
+    // we can now spend the access token in other crates. In
+    // this example we are creating an Azure Storage client
+    // using the access token.
+    let client = client::with_bearer_token(
+        &storage_account_name,
+        &authorization.access_token.secret() as &str,
+    );
+
+    // now we enumerate the containers in the
+    // specified storage account.
+    let containers = client.list_containers().finalize().await?;
+    println!("\nList containers completed succesfully: {:?}", containers);
+
+    Ok(())
+}

azure_sdk_auth_aad/src/device_code_flow.rs

@@ -0,0 +1,167 @@
+use crate::device_code_responses::*;
+use async_timer::timer::new_timer;
+use azure_sdk_core::errors::AzureError;
+use futures::stream::unfold;
+use log::debug;
+pub use oauth2::{ClientId, ClientSecret};
+use std::convert::TryInto;
+use std::sync::Arc;
+use std::time::Duration;
+use url::form_urlencoded;
+
+#[derive(Debug, Clone, Deserialize)]
+pub struct DeviceCodePhaseOneResponse<'a> {
+    device_code: String,
+    user_code: String,
+    verification_uri: String,
+    expires_in: u64,
+    interval: u64,
+    message: String,
+    // the skipped fields below do not come
+    // from the Azure answer. They will be added
+    // manually after deserialization
+    #[serde(skip)]
+    client: Arc<reqwest::Client>,
+    #[serde(skip)]
+    tenant_id: &'a str,
+    // we store the ClientId as string instead of
+    // the original type because it does not
+    // implement Default and it's in another
+    // create
+    #[serde(skip)]
+    client_id: String,
+}
+
+pub async fn begin_authorize_device_code_flow<'a, 'b>(
+    client: Arc<reqwest::Client>,
+    tenant_id: &'a str,
+    client_id: &'a ClientId,
+    scopes: &'b [&'b str],
+) -> Result<DeviceCodePhaseOneResponse<'a>, AzureError> {
+    let mut encoded = form_urlencoded::Serializer::new(String::new());
+    let encoded = encoded.append_pair("client_id", client_id.as_str());
+    let encoded = encoded.append_pair("scope", &scopes.join(" "));
+    let encoded = encoded.finish();
+
+    debug!("encoded ==> {}", encoded);
+
+    let url = url::Url::parse(&format!(
+        "https://login.microsoftonline.com/{}/oauth2/v2.0/devicecode",
+        tenant_id
+    ))?;
+
+    client
+        .post(url)
+        .header("ContentType", "application/x-www-form-urlencoded")
+        .body(encoded)
+        .send()
+        .await
+        .map_err(|e| AzureError::GenericErrorWithText(e.to_string()))?
+        .text()
+        .await
+        .map_err(|e| AzureError::GenericErrorWithText(e.to_string()))
+        .and_then(|s| {
+            serde_json::from_str::<DeviceCodePhaseOneResponse>(&s)
+                // we need to capture some variables that will be useful in
+                // the second phase (the client, the tenant_id and the client_id)
+                .map(|device_code_reponse| DeviceCodePhaseOneResponse {
+                    device_code: device_code_reponse.device_code,
+                    user_code: device_code_reponse.user_code,
+                    verification_uri: device_code_reponse.verification_uri,
+                    expires_in: device_code_reponse.expires_in,
+                    interval: device_code_reponse.interval,
+                    message: device_code_reponse.message,
+                    client: client.clone(),
+                    tenant_id,
+                    client_id: client_id.as_str().to_string(),
+                })
+                .map_err(|e| {
+                    serde_json::from_str::<crate::errors::ErrorResponse>(&s)
+                        .map(|er| AzureError::GenericErrorWithText(er.to_string()))
+                        .unwrap_or_else(|_| {
+                            AzureError::GenericErrorWithText(format!(
+                                "Failed to parse Azure response: {}",
+                                e.to_string()
+                            ))
+                        })
+                })
+        })
+}
+
+impl<'a> DeviceCodePhaseOneResponse<'a> {
+    pub fn message(&self) -> &str {
+        &self.message
+    }
+
+    pub fn stream(
+        &self,
+    ) -> impl futures::Stream<Item = Result<DeviceCodeResponse, DeviceCodeError>> + '_ {
+        #[derive(Debug, Clone, PartialEq)]
+        enum NextState {
+            Continue,
+            Finish,
+        }
+
+        unfold(
+            NextState::Continue,
+            async move |state: NextState| match state {
+                NextState::Continue => {
+                    let uri = format!(
+                        "https://login.microsoftonline.com/{}/oauth2/v2.0/token",
+                        self.tenant_id,
+                    );
+
+                    // throttle down as specified by Azure. This could be
+                    // smarter: we could calculate the elapsed time since the
+                    // last poll and wait only the delta. For now we do not
+                    // need such precision.
+                    new_timer(Duration::from_secs(self.interval)).await;
+                    debug!("posting to {}", &uri);
+
+                    let mut encoded = form_urlencoded::Serializer::new(String::new());
+                    let encoded = encoded
+                        .append_pair("grant_type", "urn:ietf:params:oauth:grant-type:device_code");
+                    let encoded = encoded.append_pair("client_id", self.client_id.as_str());
+                    let encoded = encoded.append_pair("device_code", &self.device_code);
+                    let encoded = encoded.finish();
+
+                    let result = match self
+                        .client
+                        .post(&uri)
+                        .header("ContentType", "application/x-www-form-urlencoded")
+                        .body(encoded)
+                        .send()
+                        .await
+                        .map_err(DeviceCodeError::ReqwestError)
+                    {
+                        Ok(result) => result,
+                        Err(error) => return Some((Err(error), NextState::Finish)),
+                    };
+                    debug!("result (raw) ==> {:?}", result);
+
+                    let result = match result.text().await.map_err(DeviceCodeError::ReqwestError) {
+                        Ok(result) => result,
+                        Err(error) => return Some((Err(error), NextState::Finish)),
+                    };
+                    debug!("result (as text) ==> {}", result);
+
+                    // here either we get an error response from Azure
+                    // or we get a success. A success can be either "Pending" or
+                    // "Completed". We finish the loop only on "Completed" (ie Success)
+                    match result.try_into() {
+                        Ok(device_code_response) => {
+                            let next_state = match &device_code_response {
+                                DeviceCodeResponse::AuthorizationSucceded(_) => NextState::Finish,
+                                DeviceCodeResponse::AuthorizationPending(_) => NextState::Continue,
+                            };
+
+                            Some((Ok(device_code_response), next_state))
+                        }
+                        Err(error) => Some((Err(error), NextState::Finish)),
+                    }
+                }
+                NextState::Finish => None,
+            },
+        )
+    }
+}

azure_sdk_auth_aad/src/device_code_responses.rs

@@ -0,0 +1,92 @@
+use oauth2::AccessToken;
+use std::convert::TryInto;
+use std::fmt;
+use thiserror::Error;
+
+#[derive(Debug, Clone, PartialEq, Deserialize)]
+pub struct DeviceCodeErrorResponse {
+    pub error: String,
+    pub error_description: String,
+    pub error_uri: String,
+}
+
+impl fmt::Display for DeviceCodeErrorResponse {
+    // This trait requires `fmt` with this exact signature.
+    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+        write!(f, "{}. {}", self.error, self.error_description)
+    }
+}
+
+#[derive(Debug, Clone, Deserialize)]
+pub struct DeviceCodeAuthorization {
+    pub token_type: String,
+    pub scope: String,
+    pub expires_in: u64,
+    pub access_token: AccessToken,
+    pub refresh_token: Option<AccessToken>,
+    pub id_token: Option<AccessToken>,
+}
+
+#[derive(Error, Debug)]
+pub enum DeviceCodeError {
+    #[error("Authorization declined")]
+    AuthorizationDeclined(DeviceCodeErrorResponse),
+    #[error("Bad verification code")]
+    BadVerificationCode(DeviceCodeErrorResponse),
+    #[error("Expired token")]
+    ExpiredToken(DeviceCodeErrorResponse),
+    #[error("Unrecognized error: {0}")]
+    UnrecognizedError(DeviceCodeErrorResponse),
+    #[error("Unhandled error: {0}. {1}")]
+    UnhandledError(String, String),
+    #[error("Reqwest error: {0}")]
+    ReqwestError(reqwest::Error),
+}
+
+#[derive(Debug, Clone)]
+pub enum DeviceCodeResponse {
+    AuthorizationSucceded(DeviceCodeAuthorization),
+    AuthorizationPending(DeviceCodeErrorResponse),
+}
+
+impl TryInto<DeviceCodeResponse> for String {
+    type Error = DeviceCodeError;
+
+    fn try_into(self) -> Result<DeviceCodeResponse, Self::Error> {
+        // first we try to deserialize as DeviceCodeAuthorization (success)
+        match serde_json::from_str::<DeviceCodeAuthorization>(&self) {
+            Ok(device_code_authorization) => Ok(DeviceCodeResponse::AuthorizationSucceded(
+                device_code_authorization,
+            )),
+            Err(_) => {
+                // now we try to map it to a DeviceCodeErrorResponse
+                match serde_json::from_str::<DeviceCodeErrorResponse>(&self) {
+                    Ok(device_code_error_response) => {
+                        match &device_code_error_response.error as &str {
+                            "authorization_pending" => {
+                                Ok(DeviceCodeResponse::AuthorizationPending(
+                                    device_code_error_response,
+                                ))
+                            }
+                            "authorization_declined" => Err(
+                                DeviceCodeError::AuthorizationDeclined(device_code_error_response),
+                            ),
+
+                            "bad_verification_code" => Err(DeviceCodeError::BadVerificationCode(
+                                device_code_error_response,
+                            )),
+                            "expired_token" => {
+                                Err(DeviceCodeError::ExpiredToken(device_code_error_response))
+                            }
+                            _ => Err(DeviceCodeError::UnrecognizedError(
+                                device_code_error_response,
+                            )),
+                        }
+                    }
+                    // If we cannot, we bail out giving the full error as string
+                    Err(error) => Err(DeviceCodeError::UnhandledError(error.to_string(), self)),
+                }
+            }
+        }
+    }
+}