Docs Puppet Enterprise Managing access SAML authentication Connect a SAML identity provider to PE

Connect a SAML identity provider to PE

Sections

Get URLS and the signing and encryption certificate

Connect to a Security Assertion Markup Language (SAML) identity provider to log in to PE with single sign-on (SSO). SSO authentication securely centralizes sensitive data and reduces the number of login credentials users have to remember and store. Depending on your identity provider, you can also use this workflow to connect and configure multifactor authentication (MFA) in PE.

Note: When SAML is configured, you must generate a token in the console to use CLI tools like orchestrator jobs or PuppetDB queries triggered from the command line.

An identity provider(IdP) is a service that stores and maintains user information under a single login. Okta, PingID, and Salesforce are all SAML identity providers.

The identity provider sends an assertion, or an xml document containing the required attributes for authenticating the user, to the service provider. Attributes are name/value pairs that specify pieces of information about a user, like their email or name.

The service provider receives the assertion from the identity provider via the web and confirms the attributes match the user, who then is logged into the website or application. PE is a service provider.

After connecting a SAML identity provider to PE, you can log into and out of PE through the identity provider.

Note: When using encryption with SAML, users might experience delays and timeouts when logging out if the host system that runs PE lacks sufficient entropy.

Get URLS and the signing and encryption certificate

PE provides URLs and a certificate that you must configure in your identity provider before you can configure SSO in PE. You must use the console to view the URLs and certificate if you haven't configured SSO yet. After you've configured SSO, you can retrieve them using the GET /v1/saml/meta endpoint. If you're promoting a replica, you must specify your replica's new URLs and certificate in your IdP's configuration.

In the console, on the Access control page, click the SSO tab.
Click Show configuration information.
The following configuration values are populated:
- The SAML metadata URL
- The assertion consumer service URL
- The single logout service URL
- The signing and encryption certificate
Add the URLs and certificate where appropriate to your identity provider configuration.

Attribute binding

Attribute binding links attribute names from PE to attributes in the identity provider. When configuring SSO, choose the name of the attributes for PE and map them to the corresponding values in your identity provider configuration.

There are no standard SAML attribute names, but attribute binding ensures PE and your identity provider can identify attributes from one another without having to call them the same thing. This capability allows you to connect PE to a variety of different identity providers.

For example, you might want to name the User attribute “uid” in PE, which corresponds to a unique user ID. When you configure attribute binding with your identity provider, map “uid” to the corresponding value your identity provider uses to identify the unique user ID, for example, “user.login”.

After configuring attribute binding for User in PE and in your identity provider, any time PE receives an assertion from the identity provider, it knows that “user.login” is the same thing as “uid”, and vice versa.

If you are connected to a LDAP external directory service, consider using the same attribute names you use in your LDAP configuration.

Attribute binding occurs for four attributes:

User: The login field that consistently identifies a given user across multiple platforms. If migrating from LDAP, this is the same as the "user login field".; Example: "uid"
Email: Extracts the email address of the user.; Example: "email"
Display name: Displays a friendly name for the user, usually the first and last name.; Example: "name"
Groups: Automatically associates the user groups and their assigned roles in PE. The attribute maps to the "login" value of the user group.; Example: "group"

Note: Some identity providers might not use the term "attribute" or the phrase "attribute binding" when referring to the name/value pairs.

Connect to a SAML identity provider

Use the console to set up SSO or MFA with your SAML identity provider.

Before you begin

Add URLs and the encryption and signing certificate to your identity provider configuration.

Configure attribute binding in your identity provider.

Configure users and user groups with your identity provider.

In the console, on the Access control page, click the SSO tab.
Click Configure.
Fill in the configuration information.
All fields are required except Identity provider SLO response URL, and the fields in the Contacts and Organization sections.
Commit changes.

Generate a token in the console

Use the console to generate an authentication token and use it to access APIs. If SAML is configured, you must have a token to use CLI tools like orchestrator jobs or PuppetDB queries triggered from the command line. Generate and export a token to the machine you want to run the CLI tool on.

In the console, on the My account page, click the Tokens tab.
Click Generate new token.
Under Description, enter a description for your new token.
Under Lifetime, select the length of time you want your token to be good for.
Click Get token.
Click Copy token.

Important: Store the token somewhere secure and do not share it with others. You cannot regenerate this token again once you close this page.
Click Close.

SAML configuration reference

Configure these settings in PE and your SAML identity provider to enable SSO or MFA.


Setting	Maps to	Required or optional	Definition
Display name	`display_name`	Required	A required string that identifies the IdP used for SSO or MFA login. Example: "Corporate Okta"
Identity provider entity ID	`idp_entity_id`	Required	A URL string identifying your IdP. Your IdP's configuration has this information. Example: "https://sso.example.info/entity"
Identity provider SSO URL	`idp_sso_url`	Required	The URL PE sends authentication messages to. Your IdP configuration has this information. Example: "https://idp.example.org/SAML2/SSO"
Identity provider SLO URL	`idp_slo_url`	Required	The URL PE sends the single logout request (SLO) to. Your IdP configuration has this information. Example: "https://ipd.example.com/SAML2/SLO"
Identity provider SLO response URL	`idp_slo_response_url`	Optional	An optional URL specifying an alternative location for SLO handling. Defaults to the SLO URL. Example: "https://ipd.example.com/SAML2/SLO-response"
IdP certificate	`idp_certificate`	Required	The public x509 certificate of the identity provider, in PEM format. PE uses the certificate to decrypt messages from the IdP and validate signatures. Example: -----BEGIN CERTIFICATE----- MIIGADCCA+igAwIBAgIBAjANBgkqhkiG9w0BAQsFADBqMWgwZgYDVQQDDF9QdXBw ... STkGww== -----END CERTIFICATE-----
Name ID encrypted?	`name_id_encrypted`	Optional	Indicates whether you want PE to encrypt the name-id in the logout request. Boolean, defaults to `true`.
Sign authentication requests?	`authn_request_signed`	Optional	Indicates whether you want PE to cryptographically sign authentication request it sends to the IdP. Boolean, defaults to `true`.
Sign logout response?	`logout_response_signed`	Optional	Indicates whether you want PE to cryptographically sign logout responses it sends to the IdP. Boolean, defaults to `true`.
Sign logout requests?	`logout_request_signed`	Optional	Indicates whether you want PE to cryptographically sign logout requests it sends to the IdP. Boolean, defaults to `true`.
Require signed messages?	`want_messages_signed`	Required	Indicates whether you want the IdP to cryptographically sign all responses, logout requests, and logout response messages it sends to PE. Boolean, defaults to `true`.
Require signed assertions?	`want_assertions_signed`	Required	Indicates whether you want the IdP to cryptographically sign assertion elements it sends to PE. Boolean, defaults to `true`.
Sign metadata?	`sign_metadata`	Required	Indicates whether you want PE to cryptographically sign the metadata provided for the IdP configuration. Boolean, defaults to `true`.
Require encrypted assertions?	`want_assertions_encrypted`	Required	Indicates whether you want the IdP to encrypt the assertion messages it sends to PE. Boolean, defaults to `true`.
Require name ID encrypted?	`want_name_id_encrypted`	Required	Indicates whether you want the IdP to encrypt the name-id field in messages it sends to PE. Boolean, defaults to `true`.
Requested authentication context	`requested_auth_context`	Optional	Comma separated list of authentication contexts indicating the type of user authentication PE suggest to the IdP. Authentication types are defined in the urn:oasis:names:tc:SAML:2.0:ac:classes: namespace of the SAML specification. If left blank, no authentication context is sent. Example: `urn:oasis:names:tc:SAML:2.0:ac:classes:Kerberos,urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport`
Requested authentication context comparison	`requested_auth_context_comparison`	Optional	Indicates to the IdP the strength of the authentication context PE provides. Choose from one of the following: `exact`: The requested authentication context comparison must be an exact match with one of the contexts PE provides. `minimum` (default): The requested authentication context comparison must be, at minimum, the strength of the context PE provides. `maximum`: The requested authentication context comparison is, at most, equal to the context PE provides. `better`: The requested authentication context comparison must be higher than the context PE provides.
Allow duplicated attribute name?	`allow_duplicated_attribute_name`	Required	Indicates whether PE allows duplicate attribute names in the attribute statement. Boolean, defaults to `true`.
Validate xml?	`want_xml_validation`	Required	Indicates whether you want PE to validate all xml statements it receives from your IdP. Invalid xml might cause security issues. Boolean, defaults to `true`.
Signature algorithm	`signature_algorithm`	Required	Indicates which signing algorithm PE uses to sign messages. Choose from one of the following: `rsa-sha1` `dsa-sha1` `rsa-sha256` (default) `rsa-sha384` `rsa-sha512`
Organization name	`organizational_name`	Optional	The official name of your organization.
Organization display name	`organizational_display_name`	Optional	An alternative display name for your organization
Organization URL	`organizational_url`	Optional	The URL for your company.
Organizational language	`organizational_lang`	Optional	The standard abbreviation for the preferred spoken language at your organization. Example: "en" for English
Technical contact name	`technical_support_name`	Optional	The name of the main technical contact at your organization.
Technical contact email address	`technical_support_email`	Optional	The email address for the main technical contact at your organization.
Support contact name	`support_name`	Optional	The name of the main support contact at your organization.
Support contact email address	`support_email`	Optional	The email address for the main support contact at your organization.