README.md

Google-Oauth

Description

Google-Oauth is a server-side verification library for Google oauth2.

Google-Oauth can help you to verify id_token or access_token which is generated from Google.

Usage (async)

1. Setup

To import Google-Oauth to your project, please add this line into your Cargo.toml.

[dependencies]
google-oauth = { version = "1" }

If you decided to use async function, please select an async runtime. Here are some options for you:

1. tokio
2. async-std
3. actix-web

We use tokio in our example, and refactor our main function like this:

#[tokio::main]
// #[async_std::main] // when you use [async-std]
// #[actix_web::main] // when you use [actix-web]
async fn main() {}

2. Do Verification (id_token)

You can get your client_id from Google Admin Console (or somewhere else), and an id_token has been provided from your user. They are all string-like. Use the following code to do verification:

use google_oauth::AsyncClient;

#[tokio::main]
async fn main() {
    let client_id = "your client id";
    let id_token = "the id_token";
    
    let client = AsyncClient::new(client_id);
    /// or, if you want to set the default timeout for fetching certificates from Google, e.g, 30 seconds, you can:
    /// ```rust
    /// let client = AsyncClient::new(client_id).timeout(time::Duration::from_sec(30));
    /// ```
    
    let payload = client.validate_id_token(id_token).await.unwrap(); // In production, remember to handle this error.
    
    // When we get the payload, that mean the id_token is valid.
    // Usually we use `sub` as the identifier for our user...
    println!("Hello, I am {}", &payload.sub);
    
    // If you have multiple client ids, you can:
    let client = AsyncClient::new_with_vec(vec![client_id]);
    // The validation fails when the id_token matches NONE of the provided client ids.
}

Do verification without any client id

When no client_id is provided for AsyncClient, cliend_id will not be used when validating id_token. In this case, AsyncClient will accept all client_id. However, Google issuer (iss), expiration (exp) and JWT hash CAN NOT be skipped.

3. Do Verification (AccessToken)

Sometimes, Google will return an access_token instead of id_token. Google-Oauth still provides API for validate access_token from Google.

Note: when validating access_token, we don't matter the client_id. So if you just need to validate access_token, you can simply pass an empty client_id, just like this:

use google_oauth::AsyncClient;

#[tokio::main]
async fn main() {
    let access_token = "the access_token";

    let client = AsyncClient::new("");

    let payload = client.validate_access_token(access_token).await.unwrap(); // In production, remember to handle this error.

    // When we get the payload, that mean the id_token is valid.
    // Usually we use `sub` as the identifier for our user...
    println!("Hello, I am {}", &payload.sub);
}

Warning: the result of access_token is different from the result of id_token, although they have a same field sub.

For full example, please view ./example/async_client/

Algorithm Supported

For validating id_token, Google may use these two kinds of hash algorithm to generate JWTs:

• RS256
• ES256

However, I cannot find any approach to get a valid ES256 token, and as a result, I remained a unimplemented branch, and return an Err if the JWT is ES256 hashed.

Feel free to create a new issue if you have an example. PR is welcome.

Usage (blocking)

Google-Oauth also provides a blocking client. You need to enable blocking feature:

[dependencies]
google-oauth = { version = "1", features = ["blocking"] }

You can use google_oauth::Client to validate tokens:

use google_oauth::Client;

fn main() {
    let client_id = "your client id";
    let id_token = "the id_token";

    let client = Client::new(client_id);

    let payload = client.validate_id_token(id_token).unwrap();
    
    println!("Hello, I am {}", &payload.sub);
}

For full example, please view ./examples/blocking/

WebAssembly (wasm)

Google-Oauth supports wasm, feature wasm is required.

[dependencies]
google-oauth = { version = "1", features = ["wasm"] }

You can build this library with wasm-pack build --features wasm. (cargo install wasm-pack to install first.)

If you need to import wasm into your project, you can use google_oauth::Client to run async functions.

Features

• default: enable AsyncClient.
• blocking: enable Client.
• wasm: disable AsyncClient and Client(blocking), enable Client (wasm).
• reqwest-rustls: use rustls as the TLS backend of the Reqwest client