Crate openidconnect[][src]

Expand description

OpenID Connect library.

This library provides extensible, strongly-typed interfaces for the OpenID Connect protocol. For convenience, the core module provides type aliases for common usage that adheres to the OpenID Connect Core spec. Users of this crate may define their own extensions and custom type parameters in lieu of using the core module.

Contents

Importing openidconnect: selecting an HTTP client interface

This library offers a flexible HTTP client interface with two modes:

  • Synchronous (blocking)
  • Asynchronous

For the HTTP client modes described above, the following HTTP client implementations can be used:

  • reqwest

    The reqwest HTTP client supports both the synchronous and asynchronous modes and is enabled by default.

    Synchronous client: reqwest::http_client

    Asynchronous client: reqwest::async_http_client

  • curl

    The curl HTTP client only supports the synchronous HTTP client mode and can be enabled in Cargo.toml via the curl feature flag.

    Synchronous client: curl::http_client

  • Custom

    In addition to the clients above, users may define their own HTTP clients, which must accept an HttpRequest and return an HttpResponse or error. Users writing their own clients may wish to disable the default reqwest dependency by specifying default-features = false in Cargo.toml (replacing ... with the desired version of this crate):

    openidconnect = { version = "...", default-features = false }

    Synchronous HTTP clients should implement the following trait:

    FnOnce(HttpRequest) -> Result<HttpResponse, RE>
    where RE: std::error::Error + 'static

    Asynchronous HTTP clients should implement the following trait:

    FnOnce(HttpRequest) -> F
    where
      F: Future<Output = Result<HttpResponse, RE>>,
      RE: std::error::Error + 'static

OpenID Connect Relying Party (Client) Interface

The Client struct provides the OpenID Connect Relying Party interface. The most common usage is provided by the core::CoreClient type alias.

Examples

Getting started: Authorization Code Grant w/ PKCE

This is the most common OIDC/OAuth2 flow. PKCE is recommended whenever the client has no client secret or has a client secret that cannot remain confidential (e.g., native, mobile, or client-side web applications).

Example

use openidconnect::{
    AccessTokenHash,
    AuthenticationFlow,
    AuthorizationCode,
    ClientId,
    ClientSecret,
    CsrfToken,
    Nonce,
    IssuerUrl,
    PkceCodeChallenge,
    RedirectUrl,
    Scope,
};
use openidconnect::core::{
  CoreAuthenticationFlow,
  CoreClient,
  CoreProviderMetadata,
  CoreResponseType,
  CoreUserInfoClaims,
};
use anyhow::anyhow;

use openidconnect::reqwest::http_client;
use url::Url;

// Use OpenID Connect Discovery to fetch the provider metadata.
use openidconnect::{OAuth2TokenResponse, TokenResponse};
let provider_metadata = CoreProviderMetadata::discover(
    &IssuerUrl::new("https://accounts.example.com".to_string())?,
    http_client,
)?;

// Create an OpenID Connect client by specifying the client ID, client secret, authorization URL
// and token URL.
let client =
    CoreClient::from_provider_metadata(
        provider_metadata,
        ClientId::new("client_id".to_string()),
        Some(ClientSecret::new("client_secret".to_string())),
    )
    // Set the URL the user will be redirected to after the authorization process.
    .set_redirect_uri(RedirectUrl::new("http://redirect".to_string())?);

// Generate a PKCE challenge.
let (pkce_challenge, pkce_verifier) = PkceCodeChallenge::new_random_sha256();

// Generate the full authorization URL.
let (auth_url, csrf_token, nonce) = client
    .authorize_url(
        CoreAuthenticationFlow::AuthorizationCode,
        CsrfToken::new_random,
        Nonce::new_random,
    )
    // Set the desired scopes.
    .add_scope(Scope::new("read".to_string()))
    .add_scope(Scope::new("write".to_string()))
    // Set the PKCE code challenge.
    .set_pkce_challenge(pkce_challenge)
    .url();

// This is the URL you should redirect the user to, in order to trigger the authorization
// process.
println!("Browse to: {}", auth_url);

// Once the user has been redirected to the redirect URL, you'll have access to the
// authorization code. For security reasons, your code should verify that the `state`
// parameter returned by the server matches `csrf_state`.

// Now you can exchange it for an access token and ID token.
let token_response =
    client
        .exchange_code(AuthorizationCode::new("some authorization code".to_string()))
        // Set the PKCE code verifier.
        .set_pkce_verifier(pkce_verifier)
        .request(http_client)?;

// Extract the ID token claims after verifying its authenticity and nonce.
let id_token = token_response
  .id_token()
  .ok_or_else(|| anyhow!("Server did not return an ID token"))?;
let claims = id_token.claims(&client.id_token_verifier(), &nonce)?;

// Verify the access token hash to ensure that the access token hasn't been substituted for
// another user's.
if let Some(expected_access_token_hash) = claims.access_token_hash() {
    let actual_access_token_hash = AccessTokenHash::from_token(
        token_response.access_token(),
        &id_token.signing_alg()?
    )?;
    if actual_access_token_hash != *expected_access_token_hash {
        return Err(anyhow!("Invalid access token"));
    }
}

// The authenticated user's identity is now available. See the IdTokenClaims struct for a
// complete listing of the available claims.
println!(
    "User {} with e-mail address {} has authenticated successfully",
    claims.subject().as_str(),
    claims.email().map(|email| email.as_str()).unwrap_or("<not provided>"),
);

// If available, we can use the UserInfo endpoint to request additional information.

// The user_info request uses the AccessToken returned in the token response. To parse custom
// claims, use UserInfoClaims directly (with the desired type parameters) rather than using the
// CoreUserInfoClaims type alias.
let userinfo: CoreUserInfoClaims = client
  .user_info(token_response.access_token().to_owned(), None)
  .map_err(|err| anyhow!("No user info endpoint: {:?}", err))?
  .request(http_client)
  .map_err(|err| anyhow!("Failed requesting user info: {:?}", err))?;

// See the OAuth2TokenResponse trait for a listing of other available fields such as
// access_token() and refresh_token().

OpenID Connect Provider (Server) Interface

This library does not implement a complete OpenID Connect Provider, which requires functionality such as credential and session management. However, it does provide strongly-typed interfaces for parsing and building OpenID Connect protocol messages.

OpenID Connect Discovery document

The ProviderMetadata struct implements the OpenID Connect Discovery document. This data structure should be serialized to JSON and served via the GET .well-known/openid-configuration path relative to your provider’s issuer URL.

Example

use openidconnect::{
    AuthUrl,
    EmptyAdditionalProviderMetadata,
    IssuerUrl,
    JsonWebKeySetUrl,
    ResponseTypes,
    Scope,
    TokenUrl,
    UserInfoUrl,
};
use openidconnect::core::{
    CoreClaimName,
    CoreJwsSigningAlgorithm,
    CoreProviderMetadata,
    CoreResponseType,
    CoreSubjectIdentifierType
};
use url::Url;
use anyhow;

let provider_metadata = CoreProviderMetadata::new(
    // Parameters required by the OpenID Connect Discovery spec.
    IssuerUrl::new("https://accounts.example.com".to_string())?,
    AuthUrl::new("https://accounts.example.com/authorize".to_string())?,
    // Use the JsonWebKeySet struct to serve the JWK Set at this URL.
    JsonWebKeySetUrl::new("https://accounts.example.com/jwk".to_string())?,
    // Supported response types (flows).
    vec![
        // Recommended: support the code flow.
        ResponseTypes::new(vec![CoreResponseType::Code]),
        // Optional: support the implicit flow.
        ResponseTypes::new(vec![CoreResponseType::Token, CoreResponseType::IdToken])
        // Other flows including hybrid flows may also be specified here.
    ],
    // For user privacy, the Pairwise subject identifier type is preferred. This prevents
    // distinct relying parties (clients) from knowing whether their users represent the same
    // real identities. This identifier type is only useful for relying parties that don't
    // receive the 'email', 'profile' or other personally-identifying scopes.
    // The Public subject identifier type is also supported.
    vec![CoreSubjectIdentifierType::Pairwise],
    // Support the RS256 signature algorithm.
    vec![CoreJwsSigningAlgorithm::RsaSsaPssSha256],
    // OpenID Connect Providers may supply custom metadata by providing a struct that
    // implements the AdditionalProviderMetadata trait. This requires manually using the
    // generic ProviderMetadata struct rather than the CoreProviderMetadata type alias,
    // however.
    EmptyAdditionalProviderMetadata {},
)
// Specify the token endpoint (required for the code flow).
.set_token_endpoint(Some(TokenUrl::new("https://accounts.example.com/token".to_string())?))
// Recommended: support the UserInfo endpoint.
.set_userinfo_endpoint(
    Some(UserInfoUrl::new("https://accounts.example.com/userinfo".to_string())?)
)
// Recommended: specify the supported scopes.
.set_scopes_supported(Some(vec![
    Scope::new("openid".to_string()),
    Scope::new("email".to_string()),
    Scope::new("profile".to_string()),
]))
// Recommended: specify the supported ID token claims.
.set_claims_supported(Some(vec![
    // Providers may also define an enum instead of using CoreClaimName.
    CoreClaimName::new("sub".to_string()),
    CoreClaimName::new("aud".to_string()),
    CoreClaimName::new("email".to_string()),
    CoreClaimName::new("email_verified".to_string()),
    CoreClaimName::new("exp".to_string()),
    CoreClaimName::new("iat".to_string()),
    CoreClaimName::new("iss".to_string()),
    CoreClaimName::new("name".to_string()),
    CoreClaimName::new("given_name".to_string()),
    CoreClaimName::new("family_name".to_string()),
    CoreClaimName::new("picture".to_string()),
    CoreClaimName::new("locale".to_string()),
]));

serde_json::to_string(&provider_metadata).map_err(From::from)

OpenID Connect Discovery JSON Web Key Set

The JSON Web Key Set (JWKS) provides the public keys that relying parties (clients) use to verify the authenticity of ID tokens returned by this OpenID Connect Provider. The JsonWebKeySet data structure should be serialized as JSON and served at the URL specified in the jwks_uri field of the ProviderMetadata returned in the OpenID Connect Discovery document.

Example

use openidconnect::{JsonWebKeyId, PrivateSigningKey};
use openidconnect::core::{CoreJsonWebKey, CoreJsonWebKeySet, CoreRsaPrivateSigningKey};
use anyhow;

let jwks = CoreJsonWebKeySet::new(
    vec![
        // RSA keys may also be constructed directly using CoreJsonWebKey::new_rsa(). Providers
        // aiming to support other key types may provide their own implementation of the
        // JsonWebKey trait or submit a PR to add the desired support to this crate.
        CoreRsaPrivateSigningKey::from_pem(
            &rsa_pem,
            Some(JsonWebKeyId::new("key1".to_string()))
        )
        .expect("Invalid RSA private key")
        .as_verification_key()
    ]
);

serde_json::to_string(&jwks).map_err(From::from)

OpenID Connect ID Token

The IdToken::new method is used for signing ID token claims, which can then be returned from the token endpoint as part of the StandardTokenResponse struct (or core::CoreTokenResponse type alias). The ID token can also be serialized to a string using the IdToken::to_string method and returned directly from the authorization endpoint when the implicit flow or certain hybrid flows are used. Note that in these flows, ID tokens must only be returned in the URL fragment, and never as a query parameter.

The ID token contains a combination of the OpenID Connect Standard Claims (see StandardClaims) and claims specific to the OpenID Connect ID Token (see IdTokenClaims).

Example

use chrono::{Duration, Utc};
use openidconnect::{
    AccessToken,
    Audience,
    EmptyAdditionalClaims,
    EmptyExtraTokenFields,
    EndUserEmail,
    IssuerUrl,
    JsonWebKeyId,
    StandardClaims,
    SubjectIdentifier,
};
use openidconnect::core::{
    CoreIdToken,
    CoreIdTokenClaims,
    CoreIdTokenFields,
    CoreJwsSigningAlgorithm,
    CoreRsaPrivateSigningKey,
    CoreTokenResponse,
    CoreTokenType,
};
use anyhow;

let id_token = CoreIdToken::new(
    CoreIdTokenClaims::new(
        // Specify the issuer URL for the OpenID Connect Provider.
        IssuerUrl::new("https://accounts.example.com".to_string())?,
        // The audience is usually a single entry with the client ID of the client for whom
        // the ID token is intended. This is a required claim.
        vec![Audience::new("client-id-123".to_string())],
        // The ID token expiration is usually much shorter than that of the access or refresh
        // tokens issued to clients.
        Utc::now() + Duration::seconds(300),
        // The issue time is usually the current time.
        Utc::now(),
        // Set the standard claims defined by the OpenID Connect Core spec.
        StandardClaims::new(
            // Stable subject identifiers are recommended in place of e-mail addresses or other
            // potentially unstable identifiers. This is the only required claim.
            SubjectIdentifier::new("5f83e0ca-2b8e-4e8c-ba0a-f80fe9bc3632".to_string())
        )
        // Optional: specify the user's e-mail address. This should only be provided if the
        // client has been granted the 'profile' or 'email' scopes.
        .set_email(Some(EndUserEmail::new("bob@example.com".to_string())))
        // Optional: specify whether the provider has verified the user's e-mail address.
        .set_email_verified(Some(true)),
        // OpenID Connect Providers may supply custom claims by providing a struct that
        // implements the AdditionalClaims trait. This requires manually using the
        // generic IdTokenClaims struct rather than the CoreIdTokenClaims type alias,
        // however.
        EmptyAdditionalClaims {},
    ),
    // The private key used for signing the ID token. For confidential clients (those able
    // to maintain a client secret), a CoreHmacKey can also be used, in conjunction
    // with one of the CoreJwsSigningAlgorithm::HmacSha* signing algorithms. When using an
    // HMAC-based signing algorithm, the UTF-8 representation of the client secret should
    // be used as the HMAC key.
    &CoreRsaPrivateSigningKey::from_pem(
            &rsa_pem,
            Some(JsonWebKeyId::new("key1".to_string()))
        )
        .expect("Invalid RSA private key"),
    // Uses the RS256 signature algorithm. This crate supports any RS*, PS*, or HS*
    // signature algorithm.
    CoreJwsSigningAlgorithm::RsaSsaPkcs1V15Sha256,
    // When returning the ID token alongside an access token (e.g., in the Authorization Code
    // flow), it is recommended to pass the access token here to set the `at_hash` claim
    // automatically.
    Some(&access_token),
    // When returning the ID token alongside an authorization code (e.g., in the implicit
    // flow), it is recommended to pass the authorization code here to set the `c_hash` claim
    // automatically.
    None,
)?;

Ok(CoreTokenResponse::new(
    AccessToken::new("some_secret".to_string()),
    CoreTokenType::Bearer,
    CoreIdTokenFields::new(Some(id_token), EmptyExtraTokenFields {}),
))

Asynchronous API

An asynchronous API for async/await is also provided.

Example

use openidconnect::{
    AccessTokenHash,
    AuthenticationFlow,
    AuthorizationCode,
    ClientId,
    ClientSecret,
    CsrfToken,
    Nonce,
    IssuerUrl,
    PkceCodeChallenge,
    RedirectUrl,
    Scope,
};
use openidconnect::core::{
  CoreAuthenticationFlow,
  CoreClient,
  CoreProviderMetadata,
  CoreResponseType,
};
use openidconnect::reqwest::async_http_client;
use url::Url;
use anyhow::anyhow;


// Use OpenID Connect Discovery to fetch the provider metadata.
use openidconnect::{OAuth2TokenResponse, TokenResponse};
let provider_metadata = CoreProviderMetadata::discover_async(
    IssuerUrl::new("https://accounts.example.com".to_string())?,
    async_http_client,
)
.await?;

// Create an OpenID Connect client by specifying the client ID, client secret, authorization URL
// and token URL.
let client =
    CoreClient::from_provider_metadata(
        provider_metadata,
        ClientId::new("client_id".to_string()),
        Some(ClientSecret::new("client_secret".to_string())),
    )
    // Set the URL the user will be redirected to after the authorization process.
    .set_redirect_uri(RedirectUrl::new("http://redirect".to_string())?);

// Generate a PKCE challenge.
let (pkce_challenge, pkce_verifier) = PkceCodeChallenge::new_random_sha256();

// Generate the full authorization URL.
let (auth_url, csrf_token, nonce) = client
    .authorize_url(
        CoreAuthenticationFlow::AuthorizationCode,
        CsrfToken::new_random,
        Nonce::new_random,
    )
    // Set the desired scopes.
    .add_scope(Scope::new("read".to_string()))
    .add_scope(Scope::new("write".to_string()))
    // Set the PKCE code challenge.
    .set_pkce_challenge(pkce_challenge)
    .url();

// This is the URL you should redirect the user to, in order to trigger the authorization
// process.
println!("Browse to: {}", auth_url);

// Once the user has been redirected to the redirect URL, you'll have access to the
// authorization code. For security reasons, your code should verify that the `state`
// parameter returned by the server matches `csrf_state`.

// Now you can exchange it for an access token and ID token.
let token_response =
    client
        .exchange_code(AuthorizationCode::new("some authorization code".to_string()))
        // Set the PKCE code verifier.
        .set_pkce_verifier(pkce_verifier)
        .request_async(async_http_client)
        .await?;

// Extract the ID token claims after verifying its authenticity and nonce.
let id_token = token_response
  .id_token()
  .ok_or_else(|| anyhow!("Server did not return an ID token"))?;
let claims = id_token.claims(&client.id_token_verifier(), &nonce)?;

// Verify the access token hash to ensure that the access token hasn't been substituted for
// another user's.
if let Some(expected_access_token_hash) = claims.access_token_hash() {
    let actual_access_token_hash = AccessTokenHash::from_token(
        token_response.access_token(),
        &id_token.signing_alg()?
    )?;
    if actual_access_token_hash != *expected_access_token_hash {
        return Err(anyhow!("Invalid access token"));
    }
}

// The authenticated user's identity is now available. See the IdTokenClaims struct for a
// complete listing of the available claims.
println!(
    "User {} with e-mail address {} has authenticated successfully",
    claims.subject().as_str(),
    claims.email().map(|email| email.as_str()).unwrap_or("<not provided>"),
);

// See the OAuth2TokenResponse trait for a listing of other available fields such as
// access_token() and refresh_token().

Re-exports

pub use oauth2::http;
pub use oauth2::url;

Modules

Baseline OpenID Connect implementation and types.

HTTP client backed by the curl crate. Requires “curl” feature.

OpenID Connect Dynamic Client Registration.

HTTP client backed by the reqwest crate. Requires “reqwest” feature.

HTTP client backed by the ureq crate. Requires “ureq” feature.

Structs

Access token returned by the token endpoint and used to access protected resources.

Access token hash.

Address claims.

Country portion of address.

Locality portion of address.

Postal code portion of address.

Region portion of address.

Audience claim value.

URL of the authorization server’s authorization endpoint.

Set of authentication methods or procedures that are considered to be equivalent to each other in a particular context.

Identifier for an authentication method (e.g., password or totp).

Authorization code returned from the authorization endpoint.

Authorization code hash.

A request to the authorization endpoint.

OpenID Connect client.

Client configuration endpoint URL.

Client contact e-mail address.

A request to exchange client credentials for an access token.

Client identifier issued to the client during the registration process described by Section 2.2.

OpenID Connect client name.

Client password issued to the client during the registration process described by Section 2.2.

Client homepage URL.

A request to exchange an authorization code for an access token.

Value used for CSRF protection via the state parameter.

No additional claims.

Empty (default) extra token fields.

End user’s birthday, represented as an ISO 8601:2004 YYYY-MM-DD format.

End user’s e-mail address.

End user’s family name.

End user’s given name.

End user’s middle name.

End user’s name.

End user’s nickname.

End user’s phone number.

URL of end user’s profile picture.

URL of end user’s profile page.

End user’s time zone as a string from the time zone database.

End user’s username.

URL of end user’s website.

Full mailing address, formatted for display or use on a mailing label.

An HTTP request.

An HTTP response.

OpenID Connect ID token.

OpenID Connect ID token claims.

Extends the base OAuth2 token response with an ID token.

ID token verifier.

URI using the https scheme that a third party can use to initiate a login by the Relying Party.

A request to introspect an access token.

URL using the https scheme with no query or fragment component that the OP asserts as its Issuer Identifier.

ID of a JSON Web Key.

JSON Web Key Set.

JSON Web Key Set URL.

Language tag adhering to RFC 5646 (e.g., fr or fr-CA).

Hint about the login identifier the End-User might use to log in.

URL that references a logo for the Client application.

String value used to associate a client session with an ID Token, and to mitigate replay attacks.

URL providing the OpenID Connect Provider’s data usage policies for client applications.

URL providing the OpenID Connect Provider’s Terms of Service.

A request to exchange resource owner credentials for an access token.

Code Challenge used for PKCE protection via the code_challenge parameter.

Code Challenge Method used for PKCE protection via the code_challenge_method parameter.

Code Verifier used for PKCE protection via the code_verifier parameter. The value must have a minimum length of 43 characters and a maximum length of 128 characters. Each character must be ASCII alphanumeric or one of the characters “-” / “.” / “_” / “~”.

URL providing a client application’s data usage policy.

Provider metadata returned by OpenID Connect Discovery.

URL of the client’s redirection endpoint.

Refresh token used to obtain a new access token (if supported by the authorization server).

A request to exchange a refresh token for an access token.

Access token used by a client application to access the Client Registration endpoint.

URL of the Client Registration endpoint.

URL used to pass request parameters as JWTs by reference.

Resource owner’s password used directly as an authorization grant to obtain an access token.

Resource owner’s username used directly as an authorization grant to obtain an access token.

Informs the Authorization Server of the desired authorization processing flow, including what parameters are returned from the endpoints used.

A request to revoke a token via an RFC 7009 compatible endpoint.

URL of the authorization server’s RFC 7009 token revocation endpoint.

Access token scope, as defined by the authorization server.

URL for retrieving redirect URIs that should receive identical pairwise subject identifiers.

URL for developer documentation for an OpenID Connect Provider.

Standard Claims defined by OpenID Connect Core.

Error response returned by server after requesting an access token.

Standard OAuth2 token introspection response.

Standard OAuth2 token response.

A user’s street address.

Locally unique and never reassigned identifier within the Issuer for the End-User, which is intended to be consumed by the client application.

URL for the relying party’s Terms of Service.

URL of the authorization server’s token endpoint.

User info claims.

JSON Web Token (JWT) containing user info claims.

User info request.

URL for a provider’s user info endpoint.

User info verifier.

Enums

Indicates whether requests to the authorization server should use basic authentication or include the parameters in the request body for requests in which either is valid.

Authentication flow, which determines how the Authorization Server returns the OpenID Connect ID token and OAuth2 access token to the Relying Party.

Error verifying claims.

There was a problem configuring the request.

Error retrieving provider metadata.

Error creating a JSON Web Token.

Error encountered while requesting access token.

OAuth 2.0 Token Revocation error response types.

Error verifying claims signature.

Error signing a message.

Error retrieving user info.

Traits

Additional claims beyond the set of Standard Claims defined by OpenID Connect Core.

Trait for adding extra fields to ProviderMetadata.

Client application type.

How the Authorization Server displays the authentication and consent user interface pages to the End-User.

Whether the Authorization Server should prompt the End-User for reauthentication and consent.

Claim name.

Claim type (e.g., normal, aggregated, or distributed).

Client authentication method.

Server Error Response

Error types enum.

Trait for adding extra fields to the TokenResponse.

Gender claim.

Grant type.

JSON Web Key.

Key type (e.g., RSA).

Allowed key usage.

JSON Web Encryption (JWE) content encryption algorithm.

JSON Web Encryption (JWE) key management algorithm.

JSON Web Signature (JWS) algorithm.

Trait for verifying ID token nonces.

Common methods shared by all OAuth2 token implementations.

Private or symmetric key for signing.

Response mode indicating how the OpenID Connect Provider should return the Authorization Response to the Relying Party (client).

Response type indicating the desired authorization processing flow, including what parameters are returned from the endpoints used.

A revocable token.

Subject identifier type returned by an OpenID Connect Provider to uniquely identify its users.

Common methods shared by all OAuth2 token introspection implementations.

Extends the base OAuth2 token response with an ID token.

Trait for OAuth2 access tokens.