SAML endpoints

PUT /saml

Use this endpoint to configure SAML. Authentication is required.

Request format

Accepts SAML connection settings.

Important: When changing SAML settings, you must specify all required settings in the 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.

Example curl request:

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"}'

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

Example curl request:

curl GET 'https://$(puppet config print server):4433/rbac-api/v1/saml' \
-H "X-Authentication: 0F4DITVB7HP3z8YnD95kx1W1jY0z5Pnc3ixB5uGAXzLY"

Response format

If the user is authorized and there is an existing SAML configuration, the endpoint returns 200 OK and 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.

DELETE /saml

Remove the existing SAML configuration. Authentication is required.

Request format

Example curl request:

curl DELETE 'https://$(puppet config print server):4433/rbac-api/v1/saml' \
-H "X-Authentication: 0F4DITVB7HP3z8YnD95kx1W1jY0z5Pnc3ixB5uGAXzLY"

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

Example curl request:

curl GET 'https://$(puppet config print server):4433/rbac-api/v1/saml/meta' \
-H "X-Authentication: 0F4DITVB7HP3z8YnD95kx1W1jY0z5Pnc3ixB5uGAXzLY"

Response format

If the instance is not a replica and the certificate exists, the endpoint returns 200 OK and 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 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.