axiam-sdk 1.2.2

Official Rust client SDK for AXIAM IAM
Documentation
// @generated by tools/gen_management.py from management-registry.json and
// openapi.json. DO NOT EDIT -- your changes will be overwritten. Regenerate
// with `tools/gen_management.py`; CI verifies the committed output is current.

//! The `saml` management namespace (CONTRACT §27.1).
//!
//! A tenant's SAML 2.0 identity provider (CONTRACT §29): the registry of
//! service providers, the import of an SP's metadata into a *draft*
//! registration (never a write), and the lifecycle of the IdP signing
//! credential. The protocol itself -- single sign-on, single logout, the IdP
//! metadata document -- is browser and SP-to-IdP surface under
//! /saml/v2/{tenant_id}, an SP's own SAML library speaks to it, and it is not
//! in this registry.

#![allow(clippy::too_many_arguments)]

use uuid::Uuid;

use crate::AxiamError;
use crate::client::AxiamClient;
use crate::management::models;
use crate::management::page::{Page, PageRequest, collect_pages};
use crate::management::request::{Call, Verb};
use crate::management::scope::Scope;

/// The `saml` namespace handle.
///
/// A tenant's SAML 2.0 identity provider (CONTRACT §29): the registry of
/// service providers, the import of an SP's metadata into a *draft*
/// registration (never a write), and the lifecycle of the IdP signing
/// credential. The protocol itself -- single sign-on, single logout, the IdP
/// metadata document -- is browser and SP-to-IdP surface under
/// /saml/v2/{tenant_id}, an SP's own SAML library speaks to it, and it is not
/// in this registry.
///
/// Acquiring one performs no I/O and allocates nothing meaningful (§27.2 rule
/// 1); it borrows the client and cannot outlive it.
#[derive(Clone, Copy)]
pub struct Saml<'c> {
    pub(crate) client: &'c AxiamClient,
    pub(crate) scope: Scope,
}

impl std::fmt::Debug for Saml<'_> {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("Saml").field("scope", &self.scope).finish()
    }
}

impl<'c> Saml<'c> {
    pub(crate) fn new(client: &'c AxiamClient) -> Self {
        Self {
            client,
            scope: Scope::default(),
        }
    }

    /// Address a different tenant than the client's own.
    ///
    /// §27.4 rule 3: the client's `tenant_id` is the default.
    #[must_use]
    pub fn for_tenant(mut self, tenant_id: Uuid) -> Self {
        self.scope.tenant_id = Some(tenant_id);
        self
    }

    /// `GET /api/v1/tenants/{tenant_id}/saml/idp`
    pub async fn get_idp(&self) -> Result<models::SamlIdpInfo, AxiamError> {
        let tenant_id = self.scope.tenant(self.client, "saml.get_idp")?;
        let query: Vec<(&'static str, String)> = Vec::new();
        let call = Call {
            operation: "saml.get_idp",
            verb: Verb::Get,
            path_template: "/api/v1/tenants/{tenant_id}/saml/idp",
            path: format!("/api/v1/tenants/{tenant_id}/saml/idp"),
            query: &query,
        };
        self.client
            .management_send::<_, models::SamlIdpInfo>(call, None::<&()>)
            .await
    }

    /// `GET /api/v1/tenants/{tenant_id}/saml/service-providers`
    pub async fn list_service_providers(
        &self,
        page: PageRequest,
    ) -> Result<Page<models::SamlServiceProvider>, AxiamError> {
        let tenant_id = self
            .scope
            .tenant(self.client, "saml.list_service_providers")?;
        let query = page.query();
        let call = Call {
            operation: "saml.list_service_providers",
            verb: Verb::Get,
            path_template: "/api/v1/tenants/{tenant_id}/saml/service-providers",
            path: format!("/api/v1/tenants/{tenant_id}/saml/service-providers"),
            query: &query,
        };
        self.client
            .management_send::<_, Page<models::SamlServiceProvider>>(call, None::<&()>)
            .await
    }

    /// Walk `saml.list_service_providers` to exhaustion, concatenating every
    /// page.
    ///
    /// The auto-paging form §27.4 rule 4 requires. It stops on an empty page even
    /// if `total` disagrees, so a misreporting server costs one wasted request
    /// rather than an unbounded loop.
    pub async fn list_service_providers_all(
        &self,
        start: PageRequest,
    ) -> Result<Vec<models::SamlServiceProvider>, AxiamError> {
        collect_pages(start, |p| self.list_service_providers(p)).await
    }

    /// `POST /api/v1/tenants/{tenant_id}/saml/service-providers`
    ///
    /// `sp_signing_cert_pem` must be RSA (2048 bits or more) or ECDSA on P-256,
    /// P-384 or P-521; an **ECDSA certificate verifies HTTP-POST requests only**
    /// -- the HTTP-Redirect binding is RSA-only (§29.3 rule 2).
    /// `encrypt_assertions: true` is refused while encryption is unimplemented.
    /// `entity_id` is unique per tenant (`409`) and immutable once created.
    /// Not retried on failure (§27.4 rule 8): every write on this surface is
    /// issued exactly once, including the ones that look idempotent.
    pub async fn create_service_provider(
        &self,
        body: &models::SamlServiceProviderInput,
    ) -> Result<models::SamlServiceProvider, AxiamError> {
        let tenant_id = self
            .scope
            .tenant(self.client, "saml.create_service_provider")?;
        let query: Vec<(&'static str, String)> = Vec::new();
        let call = Call {
            operation: "saml.create_service_provider",
            verb: Verb::Post,
            path_template: "/api/v1/tenants/{tenant_id}/saml/service-providers",
            path: format!("/api/v1/tenants/{tenant_id}/saml/service-providers"),
            query: &query,
        };
        self.client
            .management_send::<_, models::SamlServiceProvider>(call, Some(body))
            .await
    }

    /// `GET /api/v1/tenants/{tenant_id}/saml/service-providers/{sp_id}`
    pub async fn get_service_provider(
        &self,
        sp_id: Uuid,
    ) -> Result<models::SamlServiceProvider, AxiamError> {
        let tenant_id = self
            .scope
            .tenant(self.client, "saml.get_service_provider")?;
        let query: Vec<(&'static str, String)> = Vec::new();
        let call = Call {
            operation: "saml.get_service_provider",
            verb: Verb::Get,
            path_template: "/api/v1/tenants/{tenant_id}/saml/service-providers/{sp_id}",
            path: format!("/api/v1/tenants/{tenant_id}/saml/service-providers/{sp_id}"),
            query: &query,
        };
        self.client
            .management_send::<_, models::SamlServiceProvider>(call, None::<&()>)
            .await
    }

    /// `PUT /api/v1/tenants/{tenant_id}/saml/service-providers/{sp_id}`
    /// **This is a replacement, not a patch** (§27.4 rule 5). Its required fields
    /// must all be given, and what you do not carry over from a prior read is not
    /// preserved: an optional member left `None` is omitted, and the server
    /// applies that member's default rather than keeping the stored value --
    /// unless a note below says otherwise. Read first, change the field you mean,
    /// send the whole thing back.
    ///
    /// An omitted member takes its **default**, not its stored value: `enabled`
    /// and `sign_responses` default to `true`, `name_id_format` to `persistent`,
    /// the other flags to `false`, certificates and `slo_url` / `slo_binding` to
    /// null, the lists to empty (§29.2). Start from `get_service_provider`.
    /// `entity_id` is immutable: changing it is `400` -- register a new service
    /// provider instead (§29.3 rule 3). An ECDSA `sp_signing_cert_pem` verifies
    /// HTTP-POST requests only; HTTP-Redirect is RSA-only.
    /// Not retried on failure (§27.4 rule 8): every write on this surface is
    /// issued exactly once, including the ones that look idempotent.
    pub async fn update_service_provider(
        &self,
        sp_id: Uuid,
        body: &models::SamlServiceProviderInput,
    ) -> Result<models::SamlServiceProvider, AxiamError> {
        let tenant_id = self
            .scope
            .tenant(self.client, "saml.update_service_provider")?;
        let query: Vec<(&'static str, String)> = Vec::new();
        let call = Call {
            operation: "saml.update_service_provider",
            verb: Verb::Put,
            path_template: "/api/v1/tenants/{tenant_id}/saml/service-providers/{sp_id}",
            path: format!("/api/v1/tenants/{tenant_id}/saml/service-providers/{sp_id}"),
            query: &query,
        };
        self.client
            .management_send::<_, models::SamlServiceProvider>(call, Some(body))
            .await
    }

    /// `DELETE /api/v1/tenants/{tenant_id}/saml/service-providers/{sp_id}`
    ///
    /// Ends no session: users already signed in to the SP stay signed in there
    /// until their SP session ends (§29.3 rule 5).
    /// Not retried on failure (§27.4 rule 8): every write on this surface is
    /// issued exactly once, including the ones that look idempotent.
    pub async fn delete_service_provider(&self, sp_id: Uuid) -> Result<(), AxiamError> {
        let tenant_id = self
            .scope
            .tenant(self.client, "saml.delete_service_provider")?;
        let query: Vec<(&'static str, String)> = Vec::new();
        let call = Call {
            operation: "saml.delete_service_provider",
            verb: Verb::Delete,
            path_template: "/api/v1/tenants/{tenant_id}/saml/service-providers/{sp_id}",
            path: format!("/api/v1/tenants/{tenant_id}/saml/service-providers/{sp_id}"),
            query: &query,
        };
        self.client
            .management_send_no_content(call, None::<&()>)
            .await
    }

    /// `POST /api/v1/tenants/{tenant_id}/saml/parse-sp-metadata`
    ///
    /// **Parses and stores nothing** (§29.3 rule 6): the result is a draft to
    /// review and pass to `create_service_provider`. Exactly one of
    /// `metadata_xml` and `metadata_url` must be set; both or neither is refused
    /// locally, before any request. The metadata's own signature is not
    /// evaluated. `503` in a server built without SAML.
    /// Not retried on failure (§27.4 rule 8): every write on this surface is
    /// issued exactly once, including the ones that look idempotent.
    pub async fn parse_sp_metadata(
        &self,
        body: &models::ParseSamlSpMetadata,
    ) -> Result<models::SamlSpMetadataDraft, AxiamError> {
        crate::management::checks::parse_sp_metadata_exactly_one(body)?;
        let tenant_id = self.scope.tenant(self.client, "saml.parse_sp_metadata")?;
        let query: Vec<(&'static str, String)> = Vec::new();
        let call = Call {
            operation: "saml.parse_sp_metadata",
            verb: Verb::Post,
            path_template: "/api/v1/tenants/{tenant_id}/saml/parse-sp-metadata",
            path: format!("/api/v1/tenants/{tenant_id}/saml/parse-sp-metadata"),
            query: &query,
        };
        self.client
            .management_send::<_, models::SamlSpMetadataDraft>(call, Some(body))
            .await
    }

    /// `GET /api/v1/tenants/{tenant_id}/saml/idp-credentials`
    pub async fn list_idp_credentials(&self) -> Result<Vec<models::SamlIdpCredential>, AxiamError> {
        let tenant_id = self
            .scope
            .tenant(self.client, "saml.list_idp_credentials")?;
        let query: Vec<(&'static str, String)> = Vec::new();
        let call = Call {
            operation: "saml.list_idp_credentials",
            verb: Verb::Get,
            path_template: "/api/v1/tenants/{tenant_id}/saml/idp-credentials",
            path: format!("/api/v1/tenants/{tenant_id}/saml/idp-credentials"),
            query: &query,
        };
        self.client
            .management_send::<_, Vec<models::SamlIdpCredential>>(call, None::<&()>)
            .await
    }

    /// `POST /api/v1/tenants/{tenant_id}/saml/idp-credentials`
    ///
    /// Generates an RSA-4096 key on the server, which takes seconds; the key is
    /// never returned. An occupied slot is `409` (§29.3 rule 7).
    /// Not retried on failure (§27.4 rule 8): every write on this surface is
    /// issued exactly once, including the ones that look idempotent.
    pub async fn issue_idp_credential(
        &self,
        body: &models::IssueSamlIdpCredential,
    ) -> Result<models::SamlIdpCredential, AxiamError> {
        let tenant_id = self
            .scope
            .tenant(self.client, "saml.issue_idp_credential")?;
        let query: Vec<(&'static str, String)> = Vec::new();
        let call = Call {
            operation: "saml.issue_idp_credential",
            verb: Verb::Post,
            path_template: "/api/v1/tenants/{tenant_id}/saml/idp-credentials",
            path: format!("/api/v1/tenants/{tenant_id}/saml/idp-credentials"),
            query: &query,
        };
        self.client
            .management_send::<_, models::SamlIdpCredential>(call, Some(body))
            .await
    }

    /// `POST /api/v1/tenants/{tenant_id}/saml/idp-
    /// credentials/{credential_id}/promote`
    ///
    /// `credential_id` must be the tenant's current `next` credential; in one
    /// transaction the old `active` is retired -- its key destroyed -- and `next`
    /// becomes `active` (§29.3 rule 7).
    /// Not retried on failure (§27.4 rule 8): every write on this surface is
    /// issued exactly once, including the ones that look idempotent.
    pub async fn promote_idp_credential(
        &self,
        credential_id: Uuid,
    ) -> Result<models::SamlIdpCredentialPromotion, AxiamError> {
        let tenant_id = self
            .scope
            .tenant(self.client, "saml.promote_idp_credential")?;
        let query: Vec<(&'static str, String)> = Vec::new();
        let call = Call {
            operation: "saml.promote_idp_credential",
            verb: Verb::Post,
            path_template: "/api/v1/tenants/{tenant_id}/saml/idp-credentials/{credential_id}/promote",
            path: format!(
                "/api/v1/tenants/{tenant_id}/saml/idp-credentials/{credential_id}/promote"
            ),
            query: &query,
        };
        self.client
            .management_send::<_, models::SamlIdpCredentialPromotion>(call, None::<&()>)
            .await
    }

    /// `POST /api/v1/tenants/{tenant_id}/saml/idp-
    /// credentials/{credential_id}/retire`
    ///
    /// **Retiring the `active` credential with no successor stops SAML sign-on
    /// for the whole tenant at once** (§29.3 rule 7) -- it is the incident
    /// response to a leaked key. The key is destroyed. The safe rotation is:
    /// issue into `next`, wait until every SP has refreshed the metadata, then
    /// promote.
    /// Not retried on failure (§27.4 rule 8): every write on this surface is
    /// issued exactly once, including the ones that look idempotent.
    pub async fn retire_idp_credential(
        &self,
        credential_id: Uuid,
    ) -> Result<models::SamlIdpCredential, AxiamError> {
        let tenant_id = self
            .scope
            .tenant(self.client, "saml.retire_idp_credential")?;
        let query: Vec<(&'static str, String)> = Vec::new();
        let call = Call {
            operation: "saml.retire_idp_credential",
            verb: Verb::Post,
            path_template: "/api/v1/tenants/{tenant_id}/saml/idp-credentials/{credential_id}/retire",
            path: format!(
                "/api/v1/tenants/{tenant_id}/saml/idp-credentials/{credential_id}/retire"
            ),
            query: &query,
        };
        self.client
            .management_send::<_, models::SamlIdpCredential>(call, None::<&()>)
            .await
    }
}