Contact UsTry it for free
© 2026 Direct Cursus Technology L.L.C.

Connecting a SAML federation

Written by
Updated at April 8, 2026

SAML federation allows users to log in using an external identity provider's (IdP) accounts.

Note

You need cluster administrator rights to set up a SAML federation.

Getting started

Prepare the following information about your identity provider:

  • Single Sign-On URL (SSO URL).
  • Issuer ID.
  • PEM certificate to verify the SAML response signature.

Creating a SAML federation

  1. Create a file named saml-federation.yaml containing a description of the SAML federation:

    apiVersion: iam.stackland.yandex.cloud/v1alpha1
kind: SAMLFederation
metadata:
  name: my-federation
spec:
  description: "SAML Federation for corporate users"
  cookieMaxAge: "43200s"  # 12 hours
  issuer: "https://idp.example.com/realms/my-realm"
  ssoBinding: POST
  ssoUrl: "https://idp.example.com/realms/my-realm/protocol/saml"
  autoCreateAccountOnLogin: true
  caseInsensitiveNameIds: false
  securitySettings:
    encryptedAssertions: false
    forceAuthn: true
  certificates:
    - name: "idp-certificate"
      description: "IdP signing certificate"
      data: |
        -----BEGIN CERTIFICATE-----
        <certificate contents>
        -----END CERTIFICATE-----

    Where:

    • name: Federation name.
    • description: Federation description.
    • cookieMaxAge: Session cookie lifetime.
    • issuer: Issuer ID from the IdP settings.
    • ssoUrl: Single Sign-On URL from the IdP settings.
    • autoCreateAccountOnLogin: Create the user automatically on first login.
    • forceAuthn: Require re-authentication at each login.
    • certificates: List of certificates for verification of SAML response signatures.

  2. Apply the configuration:

    kubectl apply -f saml-federation.yaml

  3. Check the federation status:

    kubectl get samlfederation my-federation -o yaml

Setting up group mapping

Group mapping allows you to automatically add federation users to local groups based on their membership in IdP groups.

  1. Create local groups in Identity and Access Management via the management console or wait for them to be created.

  2. Add group mapping settings to the federation specification:

    apiVersion: iam.stackland.yandex.cloud/v1alpha1
kind: SAMLFederation
metadata:
  name: my-federation
spec:
  # ... other settings ...
  groupMapping:
    enabled: true
    mapping:
      - externalId: idp-admins
        internalName: stackland-cluster-admins
      - externalId: idp-developers
        internalName: developers

    Where:

    • externalId: Group name in the IdP.
    • internalName: Local group name in Identity and Access Management.

  3. Apply the changes:

    kubectl apply -f saml-federation.yaml

  4. Check the group sync status:

    kubectl get samlfederation my-federation -o jsonpath='{.status.groupMapping}'

Setting up IdP

After creating the federation in Stackland, configure your identity provider:

  1. Get the SAML response URL (ACS URL):

    kubectl get samlfederation my-federation -o jsonpath='{.status.federation.acsDomain}'

  2. In you IdP settings:

    • Specify the ACS URL given to you.
    • Set up the sending of the preferred_username attribute in the SAML response.
    • If using group mapping, set up the sending of the user group information.

Test the federation

  1. Open the Stackland management console.
  2. On the login page, select login via federation.
  3. Log in using your IdP credentials.
  4. After a successful login, check if the user has appeared in the Identity and Access Management user list.

Renewing a certificate

For zero-downtime certificate renewal:

  1. Add the new certificate to the certificates list under a different name.
  2. Apply the changes.
  3. After successful synchronization, remove the old certificate from the list.
  4. Reapply the changes.

What's next

Previous
Creating a user group
Next
Assigning access permissions