graph-rs-sdk

The SDK supports automatic token refresh using an in-memory cache. To enable this, you must include the offline_access scope in your request to ensure a refresh token is returned.

• For Authorization Code Grant: Include offline_access in your scopes when building the sign-in URL and the client.
• For Client Credentials Grant: Automatic refresh is handled natively as this flow does not rely on refresh tokens.

Note: Currently, only an in-memory token cache is available. Persistent storage mechanisms (like Azure Key Vault or macOS Keychain) are planned for future releases.

// 1. Create sign-in URL with offline_access scope
pub fn authorization_sign_in_url(client_id: &str, tenant: &str, redirect_uri: url::Url) -> Url {
  let scope = vec!["offline_access"];

  AuthorizationCodeCredential::authorization_url_builder(client_id)
          .with_redirect_uri(redirect_uri)
          .with_scope(scope)
          .url()
          .unwrap()
}

// 2. Build client with the same scope
async fn build_client(
  authorization_code: &str,
  client_id: &str,
  client_secret: &str,
  scope: Vec<String>, // must include "offline_access"
  redirect_uri: url::Url,
) -> anyhow::Result<GraphClient> {
  let mut confidential_client = ConfidentialClientApplication::builder(client_id)
          .with_auth_code(authorization_code)
          .with_client_secret(client_secret)
          .with_scope(scope)
          .with_redirect_uri(redirect_uri)
          .build();

  let graph_client = GraphClient::from(&confidential_client);

  Ok(graph_client)
}

When Microsoft Graph returns truncated data, it provides a URL (next link) to fetch the remaining data. The SDK provides several ways to handle these paging scenarios:

1. Exhaustive JSON retrieval: Use .paging().json::<T>() to automatically follow all @odata.nextLink URLs and return all responses in a VecDeque<Response<Result<T>>>. Note that this method waits for all calls to complete, so latency increases with the number of pages.
2. Streaming: Use .paging().stream::<T>() (async only) to process pages one by one as they arrive.
3. Channels: Use .paging().channel::<T>() to receive responses via a channel receiver.

Important Note on Response Types: To find the @odata.nextLink, the SDK must read the original response body. Consequently, the original reqwest::Response is consumed and replaced by a re-wrapped http::Response object that mimics the reqwest API.

#[macro_use]
extern crate serde;
use graph_rs_sdk::*;

#[derive(Debug, Serialize, Deserialize)]
pub struct User {
    pub(crate) id: Option<String>,
    #[serde(rename = "userPrincipalName")]
    user_principal_name: Option<String>,
}

#[derive(Debug, Serialize, Deserialize)]
pub struct Users {
  pub value: Vec<User>,
}

async fn paging() -> GraphResult<()> {
  let client = GraphClient::new("ACCESS_TOKEN");

  let deque = client
      .users()
      .list_user()
      .select(&["id", "userPrincipalName"])
      .paging()
      .json::<Users>()
      .await?;
  
  println!("{:#?}", deque);
  Ok(())
}

By default, with_interactive_auth returns an AuthorizationEvent<CredentialBuilder>, which allows you to react to webview events (like the user closing the window).

If you do not need to react to these specific events and simply want the credential builder, use the into_credential_builder() method. This maps the internal WebViewAuthorizationEvent into a standard Result<(AuthorizationResponse, CredentialBuilder)>.

async fn authenticate(tenant_id: &str, client_id: &str, client_secret: &str, redirect_uri: url::Url) -> anyhow::Result<()> {
    let (authorization_response, credential_builder) = AuthorizationCodeCredential::authorization_url_builder(client_id)
        .with_tenant(tenant_id)
        .with_scope(vec!["user.read"])
        .with_offline_access() // Adds offline_access as a scope which is needed to get a refresh token.
        .with_redirect_uri(redirect_uri)
        .with_interactive_auth(Secret(client_secret.to_string()), Default::default())
        .into_credential_builder()?;
    Ok(())
}

The SDK provides methods to interact with Microsoft Mail. You can retrieve mail folders, create messages, send mail, and list messages from specific folders like "Inbox".

Key methods include:

• me().mail_folder(id).get_mail_folders()
• me().messages().create_messages(&payload)
• me().send_mail(&payload)
• me().user(id).mail_folder(name).messages().list_messages()

// Get Inbox messages with a limit of 2
let response = client
    .user(USER_ID)
    .mail_folder("Inbox")
    .messages()
    .list_messages()
    .top("2")
    .send()
    .await?;

// Send a mail
let response = client
    .me()
    .send_mail(&serde_json::json!({
        "message": {
          "subject": "Meet for lunch?",
          "body": {
              "contentType": "Text",
              "content": "The new cafeteria is open."
          },
          "toRecipients": [
              { "emailAddress": { "address": "fannyd@contoso.onmicrosoft.com" } }
          ]
        },
        "saveToSentItems": "false"
      }))
    .send()
    .await?;

To use interactive authentication with a certificate, you must enable both the interactive-auth and openssl features in your Cargo.toml.

This returns an AuthorizationCodeCertificateCredentialBuilder. Like the client secret method, this builder is used to construct a ConfidentialClient for use with the GraphClient.

async fn authenticate(x509: &X509Certificate, tenant_id: &str, client_id: &str, client_secret: &str, redirect_uri: url::Url) -> anyhow::Result<AuthorizationCodeCertificateCredentialBuilder> {
    let (authorization_response, credential_builder) = AuthorizationCodeCredential::authorization_url_builder(client_id)
        .with_tenant(tenant_id)
        .with_scope(vec!["user.read"])
        .with_offline_access() // Adds offline_access as a scope which is needed to get a refresh token.
        .with_redirect_uri(redirect_uri)
        .with_certificate_interactive_auth(x509, Default::default())
        .into_credential_builder()?;

    println!("{authorization_response:#?}");

    Ok(credential_builder)
}

Interactive Authentication uses a webview (via the wry crate) to perform sign-in and handle redirect URIs. This allows for an easy integration of the OAuth Authorization Code flow into your application.

To use interactive authentication with a client secret, you must enable the interactive-auth feature in your Cargo.toml.

The process returns a CredentialBuilder (specifically an AuthorizationCodeCredentialBuilder) which stores the authorization code. You can then use this builder to create a ConfidentialClient<AuthorizationCodeCredential>, which can be passed to a GraphClient. The client handles token acquisition and automatic refreshing if the offline_access scope is requested.

Warning: Running interactive authentication in an asynchronous context may lead to crashes in some scenarios. Device code interactive auth does not currently work in async code.

async fn authenticate(tenant_id: &str, client_id: &str, client_secret: &str, redirect_uri: url::Url) -> anyhow::Result<AuthorizationCodeCredentialBuilder> {
    let (authorization_response, credential_builder) = AuthorizationCodeCredential::authorization_url_builder(client_id)
        .with_tenant(tenant_id)
        .with_scope(vec!["user.read"])
        .with_offline_access() // Adds offline_access as a scope which is needed to get a refresh token.
        .with_redirect_uri(redirect_uri)
        .with_interactive_auth(Secret(client_secret.to_string()), Default::default())
        .into_credential_builder()?;

    println!("{authorization_response:#?}");

    Ok(credential_builder)
}