Rust身份认证与访问控制库ory-client使用指南

概述

ory-client是一个Rust库，用于与Ory生态系统集成，提供OAuth 2.0、OpenID Connect(OIDC)和权限管理功能。它允许开发者轻松地将身份验证、授权和用户管理集成到Rust应用程序中。

主要功能

• OAuth 2.0和OpenID Connect实现
• 用户认证和会话管理
• 细粒度的访问控制
• 与Ory Hydra、Keto和Oathkeeper集成
• 支持多种认证流程(授权码、客户端凭证等)

安装

在Cargo.toml中添加依赖：

[dependencies]
ory-client = "0.8.0"

基本使用方法

1. 初始化客户端

use ory_client::apis::configuration::Configuration;

let config = Configuration::new();
// 或者自定义配置
let custom_config = Configuration {
    base_path: "https://your-ory-instance.com".to_string(),
    ..Default::default()
};

2. OAuth2授权码流程示例

use ory_client::apis::oauth2_api;
use ory_client::models::{AcceptOAuth2ConsentRequest, OAuth2Client};

async fn oauth2_example() -> Result<(), Box<dyn std::error::Error>> {
    let config = Configuration::new();
    
    // 获取授权URL
    let auth_url = oauth2_api::get_oauth2_authorization_url(
        &config,
        "client_id",
        "code",
        "https://your-redirect-uri.com",
        Some("openid profile email"),
        Some("state_value"),
        None,
        None,
    ).await?;
    
    println!("Authorization URL: {}", auth_url);
    
    // 处理回调并获取token
    // 这里通常是用户被重定向回你的应用后处理
    // ...
    
    Ok(())
}

3. OpenID Connect用户信息获取

use ory_client::apis::oidc_api;

async fn get_user_info(config: &Configuration, access_token: &str) {
    let user_info = oidc_api::get_userinfo(&config, access_token).await;
    match user_info {
        Ok(info) => println!("User info: {:?}", info),
        Err(e) => eprintln!("Error getting user info: {}", e),
    }
}

4. 权限检查示例

use ory_client::apis::permission_api;
use ory_client::models::RelationQuery;

async fn check_permission(config: &Configuration) {
    let query = RelationQuery {
        namespace: "files".to_string(),
        object: "document1".to_string(),
        relation: "read".to_string(),
        subject_id: Some("user123".to_string()),
        ..Default::default()
    };
    
    let result = permission_api::check_permission(&config, &query).await;
    match result {
        Ok(response) => {
            if response.allowed {
                println!("Permission granted");
            } else {
                println!("Permission denied");
            }
        }
        Err(e) => eprintln!("Error checking permission: {}", e),
    }
}

高级用法

自定义HTTP客户端

use ory_client::apis::configuration::Configuration;
use reqwest::Client;

let http_client = Client::builder()
    .timeout(std::time::Duration::from_secs(30))
    .build()?;

let config = Configuration {
    client: http_client,
    base_path: "https://your-ory-instance.com".to_string(),
    ..Default::default()
};

错误处理

use ory_client::apis::Error;

async fn handle_auth() -> Result<(), Box<dyn std::error::Error>> {
    let config = Configuration::new();
    let result = oauth2_api::get_oauth2_authorization_url(
        &config,
        "client_id",
        "code",
        "https://your-redirect-uri.com",
        Some("openid profile email"),
        Some("state_value"),
        None,
        None,
    ).await;
    
    match result {
        Ok(url) => println!("Success: {}", url),
        Err(Error::ResponseError(re)) => {
            eprintln!("API error: {} - {}", re.status, re.content);
        }
        Err(e) => {
            eprintln!("Other error: {}", e);
        }
    }
    
    Ok(())
}

完整示例Demo

下面是一个完整的OAuth2授权码流程示例，包含获取授权URL和处理回调的完整流程：

use ory_client::apis::{configuration::Configuration, oauth2_api};
use ory_client::models::OAuth2TokenResponse;
use std::collections::HashMap;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 初始化配置
    let config = Configuration {
        base_path: "https://your-ory-instance.com".to_string(),
        ..Default::default()
    };

    // 1. 获取授权URL
    let auth_url = oauth2_api::get_oauth2_authorization_url(
        &config,
        "your_client_id",
        "code",
        "https://your-redirect-uri.com/callback",
        Some("openid profile email"),
        Some("your_state_value"),
        None,
        None,
    ).await?;

    println!("请访问以下URL进行授权:\n{}", auth_url);

    // 2. 模拟用户授权后被重定向回你的应用
    // 通常在web应用中，这会由你的路由处理器处理
    let callback_url = "https://your-redirect-uri.com/callback?code=authorization_code&state=your_state_value";
    
    // 3. 从回调URL中提取授权码
    let query_params: HashMap<_, _> = url::Url::parse(callback_url)?
        .query_pairs()
        .into_owned()
        .collect();
    
    let auth_code = query_params.get("code").ok_or("Missing authorization code")?;
    let state = query_params.get("state").ok_or("Missing state")?;
    
    // 验证state参数防止CSRF攻击
    if state != "your_state_value" {
        return Err("Invalid state parameter".into());
    }

    // 4. 使用授权码获取token
    let token_response = oauth2_api::exchange_oauth2_token(
        &config,
        "authorization_code",
        "your_client_id",
        Some("your_client_secret"),
        None,
        Some(auth_code),
        Some("https://your-redirect-uri.com/callback"),
        None,
        None,
        None,
    ).await?;

    println!("Token响应: {:?}", token_response);

    // 5. 使用访问令牌获取用户信息
    if let Some(access_token) = token_response.access_token {
        let user_info = ory_client::apis::oidc_api::get_userinfo(&config, &access_token).await?;
        println!("用户信息: {:?}", user_info);
    }

    Ok(())
}

最佳实践

1. 始终验证state参数以防止CSRF攻击
2. 使用PKCE增强OAuth2安全性
3. 缓存访问令牌并处理刷新令牌
4. 在生产环境中使用HTTPS
5. 定期检查权限缓存的有效性

注意事项

• 确保正确配置Ory服务端(Hydra, Keto等)
• 遵循OAuth2和OIDC的安全最佳实践
• 在生产环境中使用适当的错误处理和日志记录

通过ory-client库，Rust开发者可以轻松集成强大的身份验证和授权功能到他们的应用程序中，同时保持Rust的安全性和性能优势。