SAML endpoints

Use the saml endpoints to configure SAML, retrieve SAML configuration details, and get the public certificate and URLs needed for configuration.

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.

Important: 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"}'
Tip: 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.

GET /saml

Retrieves the current SAML configuration settings. Authentication is required.

Request format

When Forming RBAC API requests to this endpoint, the request is a basic call with authentication, such as:
curl 'https://$(puppet config print server):4433/rbac-api/v1/saml' -H "X-Authentication:$(puppet-access show)"

Response format

If the authentication is valid and there is an existing SAML configuration, the endpoint returns 200 OK and a JSON object containing the current SAML configuration 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 404 Not Found if the SAML data is not configured.

For information about each setting, refer to SAML configuration reference.

For errors, refer to RBAC service errors.

DELETE /saml

Remove the current SAML configuration along with associated user groups and users. Authentication is required.

Request format

When Forming RBAC API requests to this endpoint, the request is a basic call with authentication, such as:
curl -X DELETE 'https://$(puppet config print server):4433/rbac-api/v1/saml' -H "X-Authentication:$(puppet-access show)"

Response format

Returns 204 No Content if the SAML configuration is removed successfully. Deletion also removes all associated user groups and users.

Returns 404 Not Found if no SAML configuration was set prior to making the DELETE request.

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

For other errors, refer to RBAC service errors.

GET /saml/meta

Retrieve the public SAML certificate and URLs you need to configure an identity provider. Authentication is required.

Request format

When Forming RBAC API requests to this endpoint, the request is a basic call with authentication, such as:
curl 'https://$(puppet config print server):4433/rbac-api/v1/saml/meta' -H "X-Authentication:$(puppet-access show)"

Response format

If the instance is not a replica and the certificate exists, the endpoint returns 200 OK and an object containing these keys:
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.
For example:
{
   "meta": "https://localhost/saml/v1/meta",
   "acs": "https://localhost/saml/v1/acs",
   "slo": "https://localhost/saml/vi/slo",
   "cert": "-----BEGIN CERTIFICATE-----\nMIIFo ..."
}

Use these 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.

For other errors, refer to RBAC service errors.