Connect a SAML identity provider to PE

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 /saml/meta endpoint. If you're promoting a replica, you must specify your replica's new URLs and certificate in your IdP's configuration.

  1. In the console, on the Access control page, click the SSO tab.
  2. Click Show configuration information and note the following values:
    • SAML metadata URL
    • SAML assertion consumer service (acs) URL
    • SAML Single Logout URL
    • Signing and Encryption Certificate
  3. Copy the URLs and certificate so you can add them to your identity provider configuration.
    Tip: Copy the entire certificate, including the begin and end tags, into it's own file.

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 in your identity provider.

  1. In the console, on the Access control page, click the SSO tab.
  2. Click Configure.
  3. Input the configuration information.
    The SAML configuration reference explains what to input in each field and which fields are optional.
  4. Commit changes.
  5. On the Access control page, go to either the User roles or User groups to configure RBAC.
    These settings determines the role(s) assigned to users when they login. Rather than assigning roles directly to individual users, user roles are assigned based on SAML group membership.

    If you remove a SAML connection, all associated user groups and users are also removed.

Generate a token in the console

Use the console to generate an authentication token that you can use to access PE APIs. If SAML is configured, you must have a token to use CLI tools, such as 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.

  1. In the console, on the My account page, click the Tokens tab.
  2. Click Generate new token.
  3. Under Description, enter a description for your new token.
  4. Under Lifetime, select the length of time you want your token to be good for.
  5. Click Get token.
  6. 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.
  7. Click Close.

SAML configuration reference

Configure these settings in Puppet Enterprise (PE) and your SAML identity provider to enable SSO or MFA. All fields are required unless otherwise noted.

Setting name System name (for RBAC API) Definition
Allow duplicated attribute name? allow_duplicated_attribute_name Boolean value indicates whether PE allows duplicate attribute names in the attribute statement. Default is true.
Display name display_name A required string that identifies the IdP used for SSO or MFA login, such as Corporate Okta.
Identity provider entity ID idp_entity_id A URL string identifying your IdP, such as https://sso.example.info/entity. Your IdP's configuration has this information.
Identity provider SLO response URL idp_slo_response_url Optional, unless required by IdP or SAML configuration. An optional URL specifying an alternative location for SLO handling. Defaults to the SLO URL. For example, https://ipd.example.com/SAML2/SLO-response.
Identity provider SLO URL idp_slo_url The URL to which PE sends the single logout request (SLO), such as https://ipd.example.com/SAML2/SLO. Your IdP configuration has this information.
Identity provider SSO URL idp_sso_url The URL to which PE sends authentication messages, such as https://idp.example.org/SAML2/SSO. Your IdP configuration has this information.
IdP certificate idp_certificate The public x509 certificate of the identity provider, in PEM format. PE uses the certificate to decrypt messages from the IdP and validate signatures. For example:
-----BEGIN CERTIFICATE-----
MIIGADCCA+igAwIBAgIBAjANBgkqhkiG9w0BAQsFADBqMW
...
STkGww==
-----END CERTIFICATE-----
Name ID encrypted? name_id_encrypted Optional, unless required by IdP or SAML configuration. Boolean value indicates whether you want PE to encrypt the name-id in the logout request. Default is true.
Organizational language organizational_lang The standard abbreviation for the preferred spoken language at your organization, such as en for English.
Organization display name organizational_display_name An alternative display name for your organization
Organization name organizational_name The official name of your organization.
Organization URL organizational_url The URL for your organization.
Requested authentication context requested_auth_context Comma-separated list of authentication contexts indicating the type of user authentication PE suggests to the IdP. Authentication types are defined in the urn:oasis:names:tc:SAML:2.0:ac:classes: namespace of the SAML specification. For example: urn:oasis:names:tc:SAML:2.0:ac:classes:Password or urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport
Requested authentication context comparison requested_auth_context_comparison Indicates to the IdP the strength of the authentication context PE provides. Choose one of the following:
  • 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.
  • exact: The requested authentication context comparison must be an exact match with one of the contexts PE provides.
  • better: The requested authentication context comparison must be higher than the context PE provides.
Require encrypted assertions? want_assertions_encrypted Boolean value indicates whether you want the IdP to encrypt the assertion messages it sends to PE. Default is true.
Require name ID encrypted? want_name_id_encrypted Boolean value indicates whether you want the IdP to encrypt the name-id field in messages it sends to PE. Default is true.
Require signed assertions? want_assertions_signed Boolean value indicates whether you want the IdP to cryptographically sign assertion elements it sends to PE. Default is true.
Require signed messages? want_messages_signed Boolean value indicates whether you want the IdP to cryptographically sign all responses, logout requests, and logout response messages it sends to PE. Default is true.
Signature algorithm signature_algorithm Indicates which signing algorithm PE uses to sign messages. Choose one of the following:
  • rsa-sha256 (default)
  • rsa-sha1
  • dsa-sha1
  • rsa-sha384
  • rsa-sha512
Sign authentication requests? authn_request_signed Optional, unless required by IdP or SAML configuration. Boolean value indicates whether you want PE to cryptographically sign authentication request it sends to the IdP. Default is true.
Sign logout requests? logout_request_signed Optional, unless required by IdP or SAML configuration. Boolean value indicates whether you want PE to cryptographically sign logout requests it sends to the IdP. Default is true.
Sign logout response? logout_response_signed Optional, unless required by IdP or SAML configuration. Boolean value indicates whether you want PE to cryptographically sign logout responses it sends to the IdP. Default is true.
Sign metadata? sign_metadata Boolean value indicates whether you want PE to cryptographically sign the metadata provided for the IdP configuration. Default is true.
Support contact email address support_email The email address of the main support contact at your organization.
Support contact name support_name The name of the main support contact at your organization.
Technical contact email address technical_support_email The email address of the main technical contact at your organization.
Technical contact name technical_support_name The name of the main technical contact at your organization.
User display name attribute binding user_display_name_attr Identifies the attribute that maps to the user's displayable name, such as First name Last name.
User email attribute binding user_email_attr Identifies the attribute that maps to the user's email address.
User group lookup attribute binding group_lookup_attr Identifies the attribute that maps to the set of user groups a user belongs to.
User lookup attribute binding user_lookup_attr Identifies the attribute that maps to the login value users provide on the login page.
Validate xml? want_xml_validation Boolean value indicates whether you want PE to validate all xml statements it receives from your IdP, because invalid xml might cause security issues. Default is true.