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

  1. In the console, on the Access control page, click the SSO tab.
  2. 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
  3. 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.

  1. In the console, on the Access control page, click the SSO tab.
  2. Click Configure.
  3. Fill in the configuration information.
    All fields are required except Identity provider SLO response URL, and the fields in the Contacts and Organization sections.
  4. 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.

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