Connect a SAML identity provider to PE
Sections
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.
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.
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.
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.
- 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".
- Extracts the email address of the user.
- Display name
- Displays a friendly name for the user, usually the first and last name.
- Groups
- Automatically associates the user groups and their assigned roles in PE. The attribute maps to the "login" value of the user group.
Connect to a SAML identity provider
Use the console to set up SSO or MFA with your SAML identity provider.
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.
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.
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
|
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 |
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 |
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 |
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 |
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 |
Sign metadata? | sign_metadata |
Required | Indicates whether you want PE to
cryptographically sign the metadata provided for the IdP configuration.
Boolean, defaults to |
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
|
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 |
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: |
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:
|
Allow duplicated attribute name? | allow_duplicated_attribute_name |
Required | Indicates whether PE allows duplicate
attribute names in the attribute statement. Boolean, defaults to
|
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 |
Signature algorithm | signature_algorithm |
Required | Indicates which signing algorithm PE
uses to sign messages. Choose from one of the following:
|
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. |