SAML endpoints
Sections
Use the SAML endpoints to configure SAML, retrieve
SAML configuration details, and, with the GET /v1/saml/meta
endpoint, get the public certificate and URLs needed for configuration.
PUT /saml
Use this endpoint to configure SAML. Authentication is required.
Request format
PUT request, including required settings you aren't changing. You
do not need to specify optional settings unless you are changing
them.The SAML configuration reference defines each setting and indicates whether the setting is required or optional. However, your specific SAML identity provider might require some of the optional settings, in which case you must treat those settings as required settings.
curl PUT 'https://$(puppet config print server):4433/rbac-api/v1/saml' \
-H "X-Authentication: 0F4DITVB7HP3z8YnD95kx1W1jY0z5Pnc3ixB5uGAXzLY" \
-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"}'Copied!Response format
{
"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"
}Copied!Returns 200 OK if the settings were updated and set.
Returns 400 Bad Request if the request is missing required settings. The SAML configuration reference specifies required settings.
Returns 403 Forbidden if the user lacks the directory_serivce:edit:* permission.
GET /saml
Retrieves the currently-configured SAML configuration. Authentication is required.
Request format
The SAML configuration reference lists settings for SAML endpoint requests.
curl GET 'https://$(puppet config print server):4433/rbac-api/v1/saml' \
-H "X-Authentication: 0F4DITVB7HP3z8YnD95kx1W1jY0z5Pnc3ixB5uGAXzLY"Copied!Response format
{
"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"
}Copied!Returns 404 Not Found if the SAML data is not configured.
DELETE /saml
Remove the existing SAML configuration. Authentication is required.
Request format
curl DELETE 'https://$(puppet config print server):4433/rbac-api/v1/saml' \
-H "X-Authentication: 0F4DITVB7HP3z8YnD95kx1W1jY0z5Pnc3ixB5uGAXzLY"Copied!Response format
Returns 204 No Content if the SAML configuration is removed successfully.
Returns 404 Not Found if no SAML configuration is set prior to making
the DELETE request.
Returns 403 Forbidden if the user lacks the directory_service:edit* permission.
GET /v1/saml/meta
Retrieve the public SAML certificate and URLs needed to configure an identity provider. Authentication is required.
Request format
curl GET 'https://$(puppet config print server):4433/rbac-api/v1/saml/meta' \
-H "X-Authentication: 0F4DITVB7HP3z8YnD95kx1W1jY0z5Pnc3ixB5uGAXzLY"Copied!Response format
| Key | Definition |
|---|---|
meta |
A URL to the public metadata endpoint for the SAML service
provider. Some IdP configurations also require this URL in the
entity-id and/or audience restriction fields |
slo |
A URL to the public logout service for SAML. |
acs |
A URL to the public assertion service for SAML. |
cert |
A string representing the public SAML certificate. |
{
"meta": "https://localhost/saml/v1/meta",
"acs": "https://localhost/saml/v1/acs",
"slo": "https://localhost/saml/vi/slo",
"cert": "-----BEGIN CERTIFICATE-----\nMIIFo ..."
}Copied!Use these key values to configure your identity provider. After configuration, your identity provider supplies the required values for configuring SAML in Puppet Enterprise (PE). You can also see this information in the PE console on the SSO tab.
Error response
Returns 404 Not Found if the public key file doesn't exist or the SAML key entries aren't present in the configuration.