[−][src]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
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(Url::parse("http://redirect")?)); // 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().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) = id_token.access_token_hash() { let actual_access_token_hash = AccessTokenHash::from_token( token_response.access_token(), &token_response.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", id_token.subject().as_str(), id_token.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(Url::parse("https://accounts.example.com/authorize")?), // 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(Url::parse("https://accounts.example.com/token")?))) // 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(id_token, EmptyExtraTokenFields {}), ))
Modules
core | Baseline OpenID Connect implementation and types. |
curl | HTTP client backed by the curl crate. |
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., |
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 |
EmptyAdditionalClaims | No additional claims. |
EmptyAdditionalProviderMetadata | Empty (default) extra |
EmptyExtraTokenFields | Empty (default) extra token fields. |
EndUserBirthday | End user's birthday, represented as an
ISO 8601:2004 |
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 |
IssuerUrl | URL using the |
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., |
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
|
PkceCodeChallengeMethod | Code Challenge Method used for PKCE protection
via the |
PkceCodeVerifier | Code Verifier used for PKCE protection via the
|
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. |
RefreshIdTokenFields | Extends the base OAuth2 token response with an optional ID token. |
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 |
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 |
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. |