Struct openid_client::issuer::Issuer

source ·

pub struct Issuer { /* private fields */ }

Expand description

Holds all the discovered values from the OIDC Issuer

Implementations§

source §

impl Issuer

Issuer Instance Creation

source

pub fn new( metadata: IssuerMetadata, interceptor: Option<RequestInterceptor> ) -> Self

Issuer

Create an Issuer instance using IssuerMetadata.

metadata - IssuerMetadata
interceptor - RequestInterceptor

No OIDC Discovery defaults are set if Issuer is created using this method.

If no introspection/revocation endpoint auth methods or algorithms are specified, value of token endpoint auth methods and algorithms are used as the the value for the said properties.

Example:

    let metadata = IssuerMetadata {
        issuer: "https://auth.example.com".to_string(),
        authorization_endpoint: Some("https://auth.example.com/authorize".to_string()),
        token_endpoint: Some("https://auth.example.com/token".to_string()),
        userinfo_endpoint: Some("https://auth.example.com/userinfo".to_string()),
        jwks_uri: Some("https://auth.example.com/certs".to_string()),
        ..IssuerMetadata::default()
    };

    let issuer = Issuer::new(metadata, None);

Example: with a request interceptor

    let metadata = IssuerMetadata {
        issuer: "https://auth.example.com".to_string(),
        authorization_endpoint: Some("https://auth.example.com/authorize".to_string()),
        token_endpoint: Some("https://auth.example.com/token".to_string()),
        userinfo_endpoint: Some("https://auth.example.com/userinfo".to_string()),
        jwks_uri: Some("https://auth.example.com/certs".to_string()),
        ..IssuerMetadata::default()
    };

    let interceptor = |request: &Request| {
        let mut headers = HeaderMap::new();

        if request.url == "https://auth.example.com/certs" {
            headers.append("foo", HeaderValue::from_static("bar"));
        }

        RequestOptions {
            headers,
            timeout: Duration::from_millis(10000),
        }
    };

    let issuer = Issuer::new(metadata, Some(Box::new(interceptor)));

    // Get jwks request will send the header foo: bar in the request
    let _ = issuer.get_jwks();

source §

impl Issuer

OIDC Issuer Discovery

source

pub fn discover( issuer: &str, interceptor: Option<RequestInterceptor> ) -> Result<Issuer, OidcClientError>

Discover OIDC Issuer

This is a blocking method. Checkout Issuer::discover_async() for async version.

Discover an OIDC Issuer using the issuer url.

issuer - The issuer url (absolute).
interceptor - RequestInterceptor

Only an absolute urls are accepted, passing in auth.example.com will result in an error.

Example:

    let _ = Issuer::discover("https://auth.example.com", None).unwrap();

Example: with .well-known/openid-configuration

Urls with .well-known/openid-configuration can also be used to discover issuer.

    let _ = Issuer::discover(
        "https://auth.example.com/.well-known/openid-configuration",
        None,
    )
    .unwrap();

Example: with interceptor

    let interceptor = |request: &Request| {
        let mut headers = HeaderMap::new();

        if request.url == "https://auth.example.com/.well-known/openid-configuration" {
            headers.append("foo", HeaderValue::from_static("bar"));
        }

        RequestOptions {
            headers,
            timeout: Duration::from_millis(10000),
        }
    };

    // The discovery request will send header foo: bar in the request headers

    let _ = Issuer::discover(
        "https://auth.example.com/.well-known/openid-configuration",
        Some(Box::new(interceptor)),
    )
    .unwrap();

source

pub async fn discover_async( issuer: &str, interceptor: Option<RequestInterceptor> ) -> Result<Issuer, OidcClientError>

Discover OIDC Issuer

This is an async method. Checkout Issuer::discover() for blocking version.

Discover an OIDC Issuer using the issuer url.

issuer - The issuer url (absolute).
interceptor - RequestInterceptor

Only an absolute urls are accepted, passing in auth.example.com will result in an error.

Example:

    let _ = Issuer::discover_async("https://auth.example.com", None)
        .await
        .unwrap();

Example: with .well-known/openid-configuration

Urls with .well-known/openid-configuration can also be used to discover issuer.

    let _ = Issuer::discover_async(
        "https://auth.example.com/.well-known/openid-configuration",
        None,
    )
    .await
    .unwrap();

Example: with interceptor

    let interceptor = |request: &Request| {
        let mut headers = HeaderMap::new();

        if request.url == "https://auth.example.com/.well-known/openid-configuration" {
            headers.append("foo", HeaderValue::from_static("bar"));
        }

        RequestOptions {
            headers,
            timeout: Duration::from_millis(10000),
        }
    };

    // The discovery request will send header foo: bar in the request headers

    let _ = Issuer::discover_async(
        "https://auth.example.com/.well-known/openid-configuration",
        Some(Box::new(interceptor)),
    )
    .await
    .unwrap();

source §

impl Issuer

OIDC Issuer Webfinger Discovery

source

pub fn webfinger( input: &str, interceptor: Option<RequestInterceptor> ) -> Result<Issuer, OidcClientError>

Webfinger OIDC Issuer Discovery

This is a blocking method. Checkout Issuer::webfinger_async() for async version.

Discover an OIDC Issuer using the user email, url, url with port syntax or acct syntax.

input - The resource.
interceptor - RequestInterceptor

Example:

    let _issuer_email = Issuer::webfinger("joe@auth.example.com", None).unwrap();
    let _issuer_url = Issuer::webfinger("https://auth.example.com/joe", None).unwrap();
    let _issuer_url_port = Issuer::webfinger("auth.example.com:3000/joe", None).unwrap();
    let _issuer_acct_email = Issuer::webfinger("acct:joe@auth.example.com", None).unwrap();
    let _issuer_acct_host = Issuer::webfinger("acct:auth.example.com", None).unwrap();

Example: with interceptor

    // This interceptor will insert a header foo: bar for the discovery request made
    // internally after webfinger request
    let interceptor = |request: &Request| {
        let mut headers = HeaderMap::new();

        if request.url == "https://auth.example.com/.well-known/openid-configuration" {
            headers.append("foo", HeaderValue::from_static("bar"));
        }

        RequestOptions {
            headers,
            timeout: Duration::from_millis(10000),
        }
    };

    let _issuer = Issuer::webfinger("joe@auth.example.com", Some(Box::new(interceptor))).unwrap();

source

pub async fn webfinger_async( input: &str, interceptor: Option<RequestInterceptor> ) -> Result<Issuer, OidcClientError>

Webfinger OIDC Issuer Discovery

This is an async method. Checkout Issuer::webfinger() for blocking version.

Discover an OIDC Issuer using the user email, url, url with port syntax or acct syntax.

input - The resource.
interceptor - RequestInterceptor

Example:

#[tokio::main]
async fn main() {
    let _issuer_email = Issuer::webfinger_async("joe@auth.example.com", None)
        .await
        .unwrap();
    let _issuer_url = Issuer::webfinger_async("https://auth.example.com/joe", None)
        .await
        .unwrap();
    let _issuer_url_port = Issuer::webfinger_async("auth.example.com:3000/joe", None)
        .await
        .unwrap();
    let _issuer_acct_email = Issuer::webfinger_async("acct:joe@auth.example.com", None)
        .await
        .unwrap();
    let _issuer_acct_host = Issuer::webfinger_async("acct:auth.example.com", None)
        .await
        .unwrap();
}

Example: with interceptor

    // This interceptor will insert a header foo: bar for the discovery request made
    // internally after webfinger request
    let interceptor = |request: &Request| {
        let mut headers = HeaderMap::new();

        if request.url == "https://auth.example.com/.well-known/openid-configuration" {
            headers.append("foo", HeaderValue::from_static("bar"));
        }

        RequestOptions {
            headers,
            timeout: Duration::from_millis(10000),
        }
    };

    let _issuer = Issuer::webfinger_async("joe@auth.example.com", Some(Box::new(interceptor)))
        .await
        .unwrap();

source §

impl Issuer

New Client implementation for Issuer

source

pub fn client( &self, metadata: ClientMetadata, interceptor: Option<RequestInterceptor>, jwks: Option<Jwks>, client_options: Option<ClientOptions> ) -> Result<Client, OidcClientError>

Creates a client from the issuer

This method creates a new Client from the issuer. A client metadata with a required client_id field is also required

metadata - ClientMetadata
interceptor - RequestInterceptor
jwks - The client jwks with private keys.
client_options - Client options.
Note: The request interceptor from the issuer is not carried over to the client. If no interceptor is provided with the method, a client with default request interceptor is created. The reason for not taking the interceptor from the issuer is to avoid the confusion of which request interceptor a Client is being created with when you are trying to create a Client from the issuer that you get back from the Client::get_issuer().

Example:

    let issuer = Issuer::discover("https://auth.example.com", None).unwrap();
     
    let client_metadata = ClientMetadata {
        client_id: Some("client_id".to_string()),
        ..ClientMetadata::default()
    };
     
    let _client = issuer.client(client_metadata, None, None, None).unwrap();

Example: with jwks

    let issuer = Issuer::discover("https://auth.example.com", None).unwrap();

    let client_metadata = ClientMetadata {
        client_id: Some("client_id".to_string()),
        ..ClientMetadata::default()
    };

    let jwk = jwk::Jwk::generate_rsa_key(2048).unwrap();

    let jwks = Jwks::from(vec![jwk]);

    let _client = issuer
        .client(client_metadata, None, Some(jwks), None)
        .unwrap();

Example: with interceptor

    let issuer = Issuer::discover("https://auth.example.com", None).unwrap();

    // Adds a foo: bar header for all urls that contains `userinfo`
    let interceptor = |request: &Request| {
        let mut headers = HeaderMap::new();

        if request.url.contains("userinfo") {
            headers.append("foo", HeaderValue::from_static("bar"));
        }

        RequestOptions {
            headers,
            timeout: Duration::from_millis(3500),
        }
    };

    let client_metadata = ClientMetadata {
        client_id: Some("client_id".to_string()),
        ..ClientMetadata::default()
    };

    let _client = issuer
        .client(client_metadata, Some(Box::new(interceptor)), None, None)
        .unwrap();