rancher/rancher · error

SAML: Unique ID field is not provided in SAML Response

Error message

SAML: Unique ID field is not provided in SAML Response

What it means

During SAML assertion processing, getSamlPrincipals reads the attribute named by the authconfig's UIDField from the flattened SAML response data. If no such attribute arrives, the server cannot build a stable unique identifier for the user, so login is aborted with this error. It is an attribute-release/mapping mismatch between IdP and the Rancher SAML config.

Source

Thrown at pkg/auth/providers/saml/saml_client.go:294

	root.HandleFunc("GET /v1-saml/okta/saml/slo", getRouteHandler("OktaSLOGet"))
	root.HandleFunc("GET /v1-saml/okta/saml/metadata", getRouteHandler("OktaMetadata"))

	root.HandleFunc("POST /v1-saml/shibboleth/saml/acs", getRouteHandler("ShibbolethACS"))
	root.HandleFunc("POST /v1-saml/shibboleth/saml/slo", getRouteHandler("ShibbolethSLO"))
	root.HandleFunc("GET /v1-saml/shibboleth/saml/slo", getRouteHandler("ShibbolethSLOGet"))
	root.HandleFunc("GET /v1-saml/shibboleth/saml/metadata", getRouteHandler("ShibbolethMetadata"))

	log.Debugf("SAML [AuthHandler]: /v1-saml routes made, mux is %p", root)
	return root
}

func (s *Provider) getSamlPrincipals(config *apiv3.SamlConfig, samlData map[string][]string) (apiv3.Principal, []apiv3.Principal, error) {
	var userPrincipal apiv3.Principal
	var groupPrincipals []apiv3.Principal
	uid, ok := samlData[config.UIDField]
	if !ok {
		// UID field provided by user is actually not there in SAMLResponse, without this we cannot differentiate between users and create separate principals
		return userPrincipal, groupPrincipals, fmt.Errorf("SAML: Unique ID field is not provided in SAML Response")
	}

	userPrincipal = apiv3.Principal{
		ObjectMeta:    metav1.ObjectMeta{Name: s.userType + "://" + uid[0]},
		Provider:      s.name,
		PrincipalType: "user",
		Me:            true,
	}

	displayName, ok := samlData[config.DisplayNameField]
	if ok {
		userPrincipal.DisplayName = displayName[0]
	}

	userName, ok := samlData[config.UserNameField]
	if ok {
		userPrincipal.LoginName = userName[0]
	}

View on GitHub (pinned to 932558d4e6)

Solutions

1. Confirm the exact attribute name carrying the unique ID in the assertion (decode the SAML response or check IdP claim config) and set uidField in the authconfig to that name.
2. At the IdP, add/repair the attribute statement or claim rule releasing that attribute to the Rancher SP entity.
3. Use SAML tracer (browser devtools extension) on a login attempt to list attributes actually sent, then align uidField.
4. Re-run the provider's testAndEnable after changing either side to validate end-to-end.

Example fix

# before (Rancher authconfig)
uidField: userName            # IdP never releases 'userName'

# after — IdP releases 'uid', so
uidField: uid
# and in the IdP app config (Okta example):
# attributeStatements: [ { name: uid, nameFormat: unspecified, values: [user.userName] } ]

// before enabling, confirm the configured UIDField appears in the IdP metadata's attribute list
func metadataReleasesAttribute(metadataXML, uidField string) bool {
    var idp struct {
        IDPSSODescriptors []struct {
            Attribute []struct{ Name string `xml:"Name,attr"` } `xml:"Attribute"`
        } `xml:"IDPSSODescriptor"`
    }
    if err := xml.Unmarshal([]byte(metadataXML), &idp); err != nil {
        return false
    }
    for _, d := range idp.IDPSSODescriptors {
        for _, a := range d.Attribute {
            if a.Name == uidField {
                return true
            }
        }
    }
    return false
}

userPrincipal, groups, err := s.getSamlPrincipals(config, samlData)
if err != nil && strings.Contains(err.Error(), "Unique ID field is not provided") {
    // config/mapping drift: surface an actionable login error, never a raw 500
    log.Errorf("uidField %q missing from assertion; attributes seen: %v", config.UIDField, reflect.ValueOf(samlData).MapKeys())
    return apiv3.Principal{}, nil, fmt.Errorf("login blocked: IdP does not release attribute %q; fix attribute statements or uidField", config.UIDField)
}

When it happens

Trigger: Logging in via the SAML provider when UIDField (e.g. "uid", "NameID", an ADFS claim name) does not match any attribute the IdP releases in its assertion; attribute statements disabled in the IdP's rancher app config; claim rules renamed.

Common situations: Okta/ADFS/Ping app configured without the needed attribute statements or claim issuance rules; UIDField changed in Rancher but not mirrored at the IdP; test users missing the attribute in directory data.

Related errors

• SAML: cannot initialize saml SP, cannot decode IDP Metadata
• can't find authprovider
• SAML [testAndEnable]: Provider %v not configured
• SAML: Cannot initialize saml SP properly, missing IDP URL/me
• SAML: Cannot initialize saml SP properly, missing SpCert in

AI-assisted analysis of rancher/rancher@932558d4e6 (2026-08-16). Data as JSON: /api/errors/076c75b6af1d0b33. Report an issue: GitHub.