Crate openidconnect

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.

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

• Google

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

extern crate base64;
extern crate openidconnect;
extern crate url;

use openidconnect::{
    AccessTokenHash,
    AuthenticationFlow,
    AuthorizationCode,
    ClientId,
    ClientSecret,
    CsrfToken,
    Nonce,
    IssuerUrl,
    PkceCodeChallenge,
    RedirectUrl,
    Scope,
};
use openidconnect::core::{CoreClient, CoreProviderMetadata, CoreResponseType};
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(
        // If using nightly Rust, a CoreAuthenticationFlow trait alias is available by
        // enabling the "nightly" feature in Cargo.toml.
        AuthenticationFlow::<CoreResponseType>::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(|| failure::format_err!("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(failure::Error::from_boxed_compat("Invalid access token".into()));
    }
}

// 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().

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

extern crate openidconnect;
extern crate serde_json;
extern crate url;

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

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(failure::Error::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};

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(failure::Error::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

extern crate chrono;
extern crate openidconnect;

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,
};

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 {}),
))

Modules

core	Baseline OpenID Connect implementation and types.
registration	OpenID Connect Dynamic Client Registration.
reqwest	HTTP client backed by the reqwest crate.

Structs

AccessToken	Access token returned by the token endpoint and used to access protected resources.
AccessTokenHash	Access token hash.
AddressClaim	Address claims.
AddressCountry	Country portion of address.
AddressLocality	Locality portion of address.
AddressPostalCode	Postal code portion of address.
AddressRegion	Region portion of address.
Audience	Audience claim value.
AuthUrl	URL of the authorization server's authorization endpoint.
AuthenticationContextClass	Set of authentication methods or procedures that are considered to be equivalent to each other in a particular context.
AuthenticationMethodReference	Identifier for an authentication method (e.g., password or totp).
AuthorizationCode	Authorization code returned from the authorization endpoint.
AuthorizationCodeHash	Authorization code hash.
AuthorizationRequest	A request to the authorization endpoint.
Client	OpenID Connect client.
ClientConfigUrl	Client configuration endpoint URL.
ClientContactEmail	Client contact e-mail address.
ClientId	Client identifier issued to the client during the registration process described by Section 2.2.
ClientName	OpenID Connect client name.
ClientSecret	Client password issued to the client during the registration process described by Section 2.2.
ClientUrl	Client homepage URL.
CodeTokenRequest	A request to exchange an authorization code for an access token.
CsrfToken	Value used for CSRF protection via the state parameter.
EmptyAdditionalClaims	No additional claims.
EmptyAdditionalProviderMetadata	Empty (default) extra ProviderMetadata fields.
EmptyExtraTokenFields	Empty (default) extra token fields.
EndUserBirthday	End user's birthday, represented as an ISO 8601:2004 YYYY-MM-DD format.
EndUserEmail	End user's e-mail address.
EndUserFamilyName	End user's family name.
EndUserGivenName	End user's given name.
EndUserMiddleName	End user's middle name.
EndUserName	End user's name.
EndUserNickname	End user's nickname.
EndUserPhoneNumber	End user's phone number.
EndUserPictureUrl	URL of end user's profile picture.
EndUserProfileUrl	URL of end user's profile page.
EndUserTimezone	End user's time zone as a string from the time zone database.
EndUserUsername	End user's username.
EndUserWebsiteUrl	URL of end user's website.
FormattedAddress	Full mailing address, formatted for display or use on a mailing label.
HttpRequest	An HTTP request.
HttpResponse	An HTTP response.
IdToken	OpenID Connect ID token.
IdTokenClaims	OpenID Connect ID token claims.
IdTokenFields	Extends the base OAuth2 token response with an ID token.
IdTokenVerifier	ID token verifier.
InitiateLoginUrl	URI using the https scheme that a third party can use to initiate a login by the Relying Party.
IssuerUrl	URL using the https scheme with no query or fragment component that the OP asserts as its Issuer Identifier.
JsonWebKeyId	ID of a JSON Web Key.
JsonWebKeySet	JSON Web Key Set.
JsonWebKeySetUrl	JSON Web Key Set URL.
LanguageTag	Language tag adhering to RFC 5646 (e.g., fr or fr-CA).
LocalizedClaim	A locale-aware claim.
LoginHint	Hint about the login identifier the End-User might use to log in.
LogoUrl	URL that references a logo for the Client application.
NoUserInfoEndpoint	The OpenID Connect Provider has no associated user info endpoint.
Nonce	String value used to associate a client session with an ID Token, and to mitigate replay attacks.
OpPolicyUrl	URL providing the OpenID Connect Provider's data usage policies for client applications.
OpTosUrl	URL providing the OpenID Connect Provider's Terms of Service.
PkceCodeChallenge	Code Challenge used for PKCE protection via the code_challenge parameter.
PkceCodeChallengeMethod	Code Challenge Method used for PKCE protection via the code_challenge_method parameter.
PkceCodeVerifier	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 "-" / "." / "_" / "~".
PolicyUrl	URL providing a client application's data usage policy.
ProviderMetadata	Provider metadata returned by OpenID Connect Discovery.
RedirectUrl	URL of the client's redirection endpoint.
RefreshToken	Refresh token used to obtain a new access token (if supported by the authorization server).
RefreshTokenRequest	A request to exchange a refresh token for an access token.
RegistrationAccessToken	Access token used by a client application to access the Client Registration endpoint.
RegistrationUrl	URL of the Client Registration endpoint.
RequestUrl	URL used to pass request parameters as JWTs by reference.
ResponseTypes	Informs the Authorization Server of the desired authorization processing flow, including what parameters are returned from the endpoints used.
Scope	Access token scope, as defined by the authorization server.
SectorIdentifierUrl	URL for retrieving redirect URIs that should receive identical pairwise subject identifiers.
ServiceDocUrl	URL for developer documentation for an OpenID Connect Provider.
StandardClaims	Standard Claims defined by OpenID Connect Core.
StandardErrorResponse	Error response returned by server after requesting an access token.
StandardTokenResponse	Standard OAuth2 token response.
StreetAddress	A user's street address.
SubjectIdentifier	Locally unique and never reassigned identifier within the Issuer for the End-User, which is intended to be consumed by the client application.
ToSUrl	URL for the relying party's Terms of Service.
TokenUrl	URL of the authorization server's token endpoint.
UserInfoClaims	User info claims.
UserInfoJsonWebToken	JSON Web Token (JWT) containing user info claims.
UserInfoRequest	User info request.
UserInfoUrl	URL for a provider's user info endpoint.
UserInfoVerifier	User info verifier.

Enums

AuthType	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.
AuthenticationFlow	Authentication flow, which determines how the Authorization Server returns the OpenID Connect ID token and OAuth2 access token to the Relying Party.
ClaimsVerificationError	Error verifying claims.
DiscoveryError	Error retrieving provider metadata.
JsonWebTokenError	Error creating a JSON Web Token.
RequestTokenError	Error encountered while requesting access token.
SignatureVerificationError	Error verifying claims signature.
SigningError	Error signing a message.
UserInfoError	Error retrieving user info.

Traits

AdditionalClaims	Additional claims beyond the set of Standard Claims defined by OpenID Connect Core.
AdditionalProviderMetadata	Trait for adding extra fields to ProviderMetadata.
ApplicationType	Client application type.
AuthDisplay	How the Authorization Server displays the authentication and consent user interface pages to the End-User.
AuthPrompt	Whether the Authorization Server should prompt the End-User for reauthentication and consent.
ClaimName	Claim name.
ClaimType	Claim type (e.g., normal, aggregated, or distributed).
ClientAuthMethod	Client authentication method.
ErrorResponse	Server Error Response
ErrorResponseType	Error types enum.
ExtraTokenFields	Trait for adding extra fields to the TokenResponse.
GenderClaim	Gender claim.
GrantType	Grant type.
JsonWebKey	JSON Web Key.
JsonWebKeyType	Key type (e.g., RSA).
JsonWebKeyUse	Allowed key usage.
JweContentEncryptionAlgorithm	JSON Web Encryption (JWE) content encryption algorithm.
JweKeyManagementAlgorithm	JSON Web Encryption (JWE) key management algorithm.
JwsSigningAlgorithm	JSON Web Signature (JWS) algorithm.
NonceVerifier	Trait for verifying ID token nonces.
OAuth2TokenResponse	Common methods shared by all OAuth2 token implementations.
PrivateSigningKey	Private or symmetric key for signing.
RefreshTokenResponse	Extends the base OAuth2 token response with an optional ID token.
ResponseMode	Response mode indicating how the OpenID Connect Provider should return the Authorization Response to the Relying Party (client).
ResponseType	Response type indicating the desired authorization processing flow, including what parameters are returned from the endpoints used.
SubjectIdentifierType	Subject identifier type returned by an OpenID Connect Provider to uniquely identify its users.
TokenResponse	Extends the base OAuth2 token response with an ID token.
TokenType	Trait for OAuth2 access tokens.