PUT /saml

Use this endpoint to configure SAML. Authentication is required.

Request format

When Forming RBAC API requests to this endpoint, the content type is application/json. The body must be a JSON object containing, at minimum, all required SAML setting keys.

When changing any SAML settings, you must specify all required settings in the request body, including required settings that you aren't changing. However, you don't need to specify optional settings unless you are changing them.

If you omit a required setting, the setting is removed or reset to the default value.

The SAML configuration reference indicates which settings are required or optional. However, your specific SAML configuration might require some of the optional settings, in which case you must treat those settings as required settings.

Example curl request:

curl -X PUT "https://$(puppet config print server):4433/rbac-api/v1/saml" \
-H "X-Authentication:$(puppet-access show)" \
-H "Content-type: application/json" \
-d '{"display_name": "Corporate Okta",
     "idp_sso_url": "https://idp.example.org/SAML2/SSO",
     "idp_slo_url": "https://ipd.example.com/SAML2/SLO", 
     "idp_certificate": [<certificate>],
     "want_messages_signed": true,
     "want_assertions_signed": true,
     "sign_metadata": true,
     "want_assertions_encrypted": true,
     "want_name_id_encrypted": true,
     "allow_duplicated_attribute_name": true,
     "want_xml_validation": true,
     "signature_algorithm": "rsa-sha256",
     "requested_authn_context_comparison": "exact",
     "user_display_name_attr": "test",
     "user_lookup_attr": "test_lookup",
     "requested_auth_context": "test-request",
     "group_lookup_attr": "group_lookup_test",
     "user_email_attr": "email_attr", 
     "idp_entity_id": "entity_id"}'

If you already have a SAML configuration, you can use the GET /saml endpoint to retrieve the current settings object and use it as a template for your PUT /saml request. This also helps avoid accidentally omitting a setting.

Response format

If you provided new settings, the endpoint returns 201 Created and the new settings. For example:

{
  "want_xml_validation":true,
  "sign_metadata":true,
  "requested_authn_context_comparison":"exact",
  "want_assertions_encrypted":true,
  "want_name_id_encrypted":true,
  "want_messages_signed":true,
  "signature_algorithm":"rsa-sha256",
  "user_display_name_attr":"test",
  "want_assertions_signed":true,
  "user_lookup_attr":"test_lookup",
  "requested_auth_context":"test-request",
  "allow_duplicated_attribute_name":true,
  "idp_sso_url":"https://idp.example.org/SAML2/SSO",
  "group_lookup_attr":"group_lookup_test",
  "idp_certificate":["MIIGADCCA+igAwIBAgIBAjANBgkqhkiG9w0BAQsFADBqMWgwZgYDVQQDDF9QdXBw"],
  "user_email_attr":"email_attr",
  "display_name":"Corporate Okta",
  "idp_entity_id":"entity_id",
  "idp_slo_url":"https://ipd.example.com/SAML2/SLO"
}

Returns 200 OK if you changed existing settings, and the changes were applied successfully.

Returns 400 Bad Request if the request was missing required settings. The SAML configuration reference specifies required settings.

Returns 403 Forbidden if the user lacks the directory_serivce:edit:* permission.

For other errors, refer to RBAC service errors .