Configure PAM as an Identity Provider (IdP)

You can configure Privileged Access Manager as an Identity Provider (IdP) to provide authentication services to a SAML 2.0 Service Provider (SP).
capam32
HID_ImportSAML2SPMetadataPanel
You can configure
Privileged Access Manager
as an Identity Provider (IdP) to provide authentication services to a SAML 2.0 Service Provider (SP). The
PAM
IdP supports the HTTP POST binding for sending messages.
This topic contains the instructions to configure
PAM
as an IdP:

Prerequisites for SAML Configuration

Before you configure the appliance as an IdP, complete the following tasks:
Provision User Accounts at Each Side
The IdP and SP must have user accounts with matching user names. Users must have permission to access resources at the SP.
Configure SAML Global Settings in the UI
Before you configure the IdP configuration, confirm the default SAML settings.
Follow these steps
:
  1. Select
    Settings, Global Settings
    .
  2. Select the
    SAML
    tab.
  3. Verify the following two settings:
    • Require Inherited SAML Auth:
      When the authentication method for a user group is set to SAML, this option applies SAML authentication to all user group members. The appliance disregards the authentication method for each individual group member. This setting is selected by default.
    • SAML Re-authentication Period (Minutes)
      This setting applies only when
      PAM
      is the IdP.  This setting specifies the minutes of inactivity before a session with a
      PAM
      IdP expires. A subsequent SSO request requires the user to log in again. Default: 60 minutes
Obtain a Certificate to Sign Authentication Responses
To sign and encrypt SAML responses for an SP, the
PAM
IdP must have a signed certificate from a Certificate Authority.
To obtain an SSL certificate, following these steps:
These steps apply for a single instance of
PAM
and for a cluster. In a cluster, complete the following procedure
only
on the first member of the primary site.
  1. In the UI, navigate to
    Configuration
    ,
    Security
    ,
    Certificates
    .
  2. On the
    Create
    page, select
    CSR
    (Certificate Signing Request). When you create a CSR, the appliance creates the CSR and a private key file.
    For information about completing the CSR form, see Create a Self-Signed Certificate or a CSR.
  3. Download the CSR and send it to the Certificate Authority.
    The Certificate Authority returns a certificate file and a CRL.
  4. After you have the certificate file, go to
    Configuration
    ,
    Security
    ,
    Certificates
    .
  5. Select the
    Upload
    page and configure the following options:
    • Type:
      Certificate
    • Other Options
      : X509
  6. Select
    Upload
    . The certificate is now available to the appliance.
    For a cluster, you must copy the certificate and the private key to all other cluster members. For instructions, continue to the next procedure.
Upload Key/Certificates In a Clustered environment
In a cluster, the IdP configuration is automatically replicated across all cluster members. The certificate is not replicated. You must copy the certificate and private key from the first member of the primary site to every other cluster member.
On the first member of the primary site,
follow these steps
  1. Go to
    Configuration, Security, Certificates.
  2. Go to the
    Download
    page and download the private key file to your local system.
  3. Create a file using a text editor.
  4. Into this file, copy the contents of the private key file and the certificate file from the Certificate Authority. The private key file was generated when you created the CSR.
  5. Save the new file.
On
every other member
of the cluster (excluding the first member of the primary site), f
ollow these steps:
  1. Log in to the UI and select
    Configuration, Security, Certificates.
  2. Select the
    Upload
    tab and set the following fields:
    • Type: Certificate with Private Key
    • Other options: PKCS
  3. Select
    Choose file
    and select the new, combined file.
  4. Select
    Upload
    .

Configure
PAM
as an IdP

A SAML SSO partnership is between an SP and IdP. The SP has the resources that users request while the IdP has the information to authenticate users who make the requests. The IdP returns an assertion that contains information about the user. The SP uses this information to determine whether to grant access to a user.
In a clustered environment, the appliance replicates the IdP configuration from the first member of the primary site to other members across the cluster. The exception is the key/certificate file that encrypts responses. You manually copied the key/certificate file to each member of a cluster in the previous procedure.
To configure
PAM
as an IdP, follow these steps:
  1. For clustered environments only:
    At the first member of the primary site, turn off the cluster. If the cluster is active, you cannot enable the IdP settings.
  2. Go to
    Configuration
    ,
    Security
    ,
    SAML
    ,
    IdP Configuration
    tab.
  3. Complete the following settings listed:
    • Status:
      Indicates whether the IdP is enabled. Enable this setting to complete the IdP configuration.
    • Entity ID:
      Enter a unique test string to identify this IdP.
    • Fully Qualified Hostname
      : Enter
      one
      of the following values. Ensure you specify the fully qualified host name.
      • For a single instance, enter the value of the IdP host name, such as capam.example.com.
      • For a primary cluster member, enter the VIP address or VIP host name.
      Inform your federation partners to use the fully qualified host name when accessing the
      PAM
      IdP.
    • Signature Algorithm:
      Select the encryption algorithm to sign certificates.
    • IdP Certificate:
      Select a certificate to sign assertions. Use the default certificate, gkcert.crt, installed with
      PAM
      or a certificate that you uploaded in the previous procedure.
  4. Optionally, select
    Download IdP metadata
    to generate an XML file and send it to the remote SP.
The configuration is complete. If you change any of these settings, select
Update IdP Configuration
.
For details about SAML metadata, see the SAML specifications.
Example: Configure SAML SSO to an AWS SP
The following example shows how to set up federated SSO between a
PAM
IdP and Amazon Web Services (AWS) as the SP. In this example, the configuration relies on metadata.
The process is reflected in the following picture:
saml sso with AWS SP
saml sso with AWS SP
Download IdP Metadata and Send it to the AWS SP
To establish trusted communication between the IdP and AWS SP, first configure and download the IdP metadata file. The downloaded file, named idp-metadata.xml, describes the IdP-supported SAML services. The file contains:
  • Information about how an SP can send authentication requests to the IdP
  • Certificate (public key) for verifying the signed assertions
  • FQDN or IP address of the
    PAM
    server
    If you change the FQDN or the certificate changes, update the IdP metadata and resend the file to the SP.
Follow these steps:
This procedure assumes that the IdP is already enabled.
  1. Log in to the
    PAM
    UI as a Configuration Administrator.
  2. Navigate to
    Configuration
    ,
    Security
    ,
    SAML
    . Select the
    IdP Configuration
    tab.
  3. Enter values for the following fields:
    • Entity ID
      : Assign a name that identifies this IdP.
      This ID is included in the metadata file and in assertions.
    • Fully Qualified Hostname
      : Enter the fully qualified name of the IdP host. The default example is idp.example.com.
    • Signature Algorithm:
      Select the encryption algorithm that is used to sign the IdP certificate
    • IdP Certificate:
      Select the certificate and key you are currently using for the appliance.
  4. Select
    Update IdP Configuration
    to apply the current certificate, host name, and your assigned ID.
    You receive a confirmation message at the top of the page.
  5. Select
    Download IdP Metadata
    to save the idp-metadata.xml file locally.
  6. At AWS, import the IdP metadata file, as instructed in the next procedure.
Import IdP Metadata to Create an AWS IAM Resource
A
PAM
administrator sends the IdP metadata to AWS. An AWS Administrator must import the metadata file to its SP endpoint. The file provides the necessary information for AWS to make authentication requests to
PAM
.
CAUTION!
The following procedure describes a product that is independent of
CA Technologies
. The procedure is provided only as an example. You might encounter different features or different appearance.
An AWS administrator must follow these steps
:
  1. Log in to the AWS Management Console and navigate to
    Services
    ,
    IAM
    ,
    Identity Providers
    .
  2. Select
    Create Provider
    and complete the following settings:
    • Provider Type:
      Select SAML.
    • Provider Name:
      Enter a name to identify the
      PAM
      IdP.
    • Metadata Document:
      Locate the IdP metadata sent by the
      PAM
      Administrator.
  3. Select
    Next Step
    then confirm the configuration by selecting
    Create
    .
  4. In the left pane, select
    Roles, Create New Role
    .
  5. Enter a
    Role Name
    , and select
    Next Step
    .
  6. On the Select Role Type page:
    1. Select
      Role for Identity Provider Access
    2. Select
      Grant Web Single Sign-On (WebSSO) access to SAML providers
  7. In the next panel, select the SAML provider that you created in the previous steps. Select
    Next Step.
  8. Continue past
    the
    Verify Role Trust
    page. In this example, you do not need to edit the Verify Role Trust: Policy Document.
  9. On the
    Attach Policy
    page, we recommend that you use select one of the pre-built policy templates, such as
    Amazon EC2 Read Only Access
    . If you are testing on a public EC2 instance, do not let others log in to your box. Select
    Next Step
    .
  10. Review the confirmation then select
    Create Role
    . Your new role appears in the roles list.
Your AWS account is now configured to communicate with the
PAM
IdP.
Import AWS SP Metadata at the IdP
AWS uses the concept of roles for authentication. When the IdP generates the authentication response, the assertion must contain role data for the user being authenticated. The role definition and other information are in the AWS SP metadata. The file also includes the attributes the SP expects in the IdP authentication response.
The AWS SAML metadata file is available at: https://signin.aws.amazon.com/static/saml-metadata.xml. After you obtain the file, import it into
PAM
.
Follow these steps:
  1. Log in to the
    PAM
    UI as a Configuration Administrator.
  2. Select
    Services
    ,
    Import SAML 2 SP Metadata
    .
  3. Select
    Choose file
    and browse to the AWS SP metadata file.
  4. Select
    Import SAML 2.0 SP Metadata
    . A message confirms the import.
    After the import, the appliance creates two objects:
    • A web portal service. The name of the service matches the SP Entity ID in the metadata file. In this example, the service is called
      AWS Management Console Single Sign-On
      .
    • A device with an address of the Assertion Consumer Service at the SP.
  5. Navigate to
    Services
    ,
    TCP/UDP Services
    and select the new web portal service and update it.
  6. Ensure that the Auto Login Method field is set to SAML2.0 SSO POST.
  7. Select the
    SAML SSO
    Info
    tab and configure the following fields:
    • Initiating Party
      : Select
      IdP-Initiated
    • Require Signed Authn Requests
      : Clear the checkbox. The AWS SP does not send signed authentication requests.
    For information about the other fields on this page, see Configure Automatic Login to Web Portals.
After you complete the procedures,
PAM
can provide an assertion to AWS. Based on the assertion, AWS can permit access to the requested resource.
Create a Policy for Users to Access to AWS Resources
For a user to gain access to an AWS resource, set up a policy for that user at the appliance. The policy is made up of a TCP/UDP service and a device that the appliance automatically creates when you imported the SP metadata. The policy also includes selected attributes that the AWS SP accepts in the assertion response.
Follow these steps:
  1. Log in to the
    PAM
    UI.
  2. Select
    Policy, Manage Policies, Add.
  3. On the
    Association
    panel, select a user and the device
    signin.aws.amazon.com
    . This device is the one automatically generated based on the SP metadata.
  4. On the
    Services
    panel, select the
    AWS Management Console Single Sign-On
    service.
  5. On the
    SAML
    panel, add the following attributes under the
    Requested Attributes
    column:
    • Subject Name Identifier
      : The available name identifier format is
      associated with the TCP/UDP service
    • RoleSessionName
      : Assign a label in the
      Attribute
      column. Use any identifier.
    • RoleEntitlement
      : Select Constant in the
      Attribute
      column. In the
      Value
      column, enter the concatenated AWS ARNs for the IAM role and the Identity Provider, separated by a comma. For example:
      arn:aws:iam::123456789012:role/MyAWSroleForMyIDP,arn:aws:iam::123456789012:saml-provider/AWSstoredMetadataForMyIDP
      The following picture shows an example:
    aws_sample_policy.png
  6. Select
    OK
    to save the policy.
The user can now access the AWS federated resource without having to log in.
Example: Configure SAML SSO to a Google SP
You can work with an SP that does not provide metadata. In this example,
PAM
IdP is configured for SSO with a Google SP. Google does not use metadata to exchange information to or from its partners.
The process is reflected in the following picture:
SAML SSO Google Example
SAML SSO Google Example
Identify the IdP at Google
At Google, the
PAM
IdP must be configured so it can authenticate Google accounts.
The following procedure describes a product that is independent of
CA Technologies
. The procedure is provided only as an example. You might encounter different features or appearance.
Follow these steps:
  1. Log in to the Google Admin Console (https://admin.google.com).
  2. From the main menu at the top left, select the Security, then scroll down the page and select
    Set up single sign-on (SSO)
    .
  3. Scroll down the page and select the checkbox
    Setup SSO with third party identity provider.
  4. Enter values for the following fields:
    • Sign-in page URL
      :
      https://
      capam_IP_or_hostname
      /
      idp/profile/SAML2/Redirect/SSO
    • Sign-out page URL:
      PAM
      does not support single sign-out. Enter
      https://
      capam_ip or hostname
      /
      as a placeholder.
    • Change password URL
      :
      PAM
      does not support password changes. Enter https://capam_ip or hostname/ as a placeholder.
    • Verification certificate
      : Upload the certificate from
      PAM
      IdP. This certificate works with the private key that is used to sign the SAML response. To obtain this certificate, take
      one
      of the following actions:
      • Copy the certificate from the IdP metadata file.
      • Download the certificate from the appliance. Select
        PAM
        Configuration
        ,
        Security
        ,
        Certificates
        , and go to the
        Download
        tab.
  5. Select
    Use a domain-specific issuer
    .
  6. Optionally, to allow a specific set of users access to the application, specify entries in the
    Network masks
    field.
  7. Continue to the next procedure.
Configure a Service to Authenticate Google Users
Set up a service at the IdP that represents the Google SP. No metadata is available to set up this service. Obtain the necessary information from the SP.
Follow these steps:
  1. Log in to the
    PAM
    UI.
  2. Navigate to
    Services, Manage TCP/UDP Services, Add.
  3. On the
    Basic Info
    panel, configure the settings with the following values:
    • Service Name
      : Entity ID of the Google SP. For this example, GoogleApps.
    • Local IP
      : Address of the end-user local host, such as the user laptop, in the format 127.0.0.5. Do not use an address of an existing service.
    • Ports
      . Enter the ports of the local host, such as 443:4430.
    • Protocol:
      TCP
    • Application Protocol:
      Web Portal.
    • Auto Login Method:
      SAML2.0 SSO POST
    • Launch URL:
      URL for the ACS, using the format: https://<Local IP>:<First Port>/a/
      google_domain
      /acs
      Enter the literal string
      <Local IP>:<First Port>. These entries are
      not
      placeholders. Replace
      google_domain
      with the domain of your Google services, such as calendar or email. This domain is the location consuming SAML assertions.
  4. In the
    SAML SSO
    Info
    panel, configure the fields with the following values
    • SAML Entity ID
      : google.com/a/
      google_domain
    • Initiating Party
      : SP-initiated
    • Require Signed Authn Requests
      : Clear the checkbox.
    • Encryption
      : Select None.  Google applications do not support encrypted assertions.
      If the SP does support encryption, you can select the
      Name ID
      or
      Assertion
      option. Then, copy the certificate from the SP in the
      PEM Encryption Certificate
      field.
  5. On the
    SAML SSO Attributes page,
    select the name identifier format urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified
  6. Select
    OK
    .
Create a Device Representing Google
Add a device that identifies the Google SP.
Follow these steps:
  1. Select
    Devices, Manage Devices, Add
    .
  2. Most of the fields are self-explanatory, but note the following entries:
    • Address
      : Enter the fully qualified domain name of the server hosting the ACS. You can extract the address from the ACS URL, for example: https://www.google.com/a/
      your_google_domain
      /acs. The device address that is provisioned in
      PAM
      is www.google.com.
    • Device Type:
      Access
    • Services
      tab: Select the
      TCP/UDP service that you configured for the SP in the previous procedure.
  3. Select
    OK
    to save the device entry.
Create an IdP User Matching the SP User
Create a user with a user name matching a Google user account that can log in to applications.
Follow these steps:
  1. Select
    Users, Manage Users, Add
    .
  2. Most of the fields on the tabs are self-explanatory.
  3. In the Roles panel, select the applicable user role for the user logging in to
    PAM
    simply to access the SP.
  4. Select
    OK
    to save the user entry.
Create a Policy for Users to Access to Google Applications
For a user to gain access to a Google application, set up a policy for that user at the appliance. The policy is made up of a TCP/UDP service, the device, and the user entry you created in the previous procedures.
Follow these steps:
  1. Log in to the
    PAM
    UI.
  2. Select
    Policy, Manage Policies, Add.
  3. On the
    Association
    panel, select a user and the device with the name
    www.google.com
    .
  4. On the
    Services
    panel, select the
    GoogleApps
    .
  5. On the
    SAML
    panel, add the following attribute entry: Attribute entry with the following values:
    • Requested Attribute:
      Subject Name Identifier. This attribute is always required.
    • Name Identifier Format
      : urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified
    • Attribute:
      Email
  6. Select
    OK
    to save the policy.
The user can now single sign-on to the Google application.

SAML SSO User Experience

When a user makes a request, there are two types of communication flows:
  • IdP-initiated: The user starts at the IdP and gets redirected to the SP.
  • SP-initiated: The user begins at the SP and the SP sends an authentication request to the IdP. The IdP responds with an assertion, which identifies the user.
The two SAML SSO configuration examples illustrate each type of flow.
IdP-initiated SSO to the AWS Management Console
In the AWS example, the service you configured to the AWS Management Console is for IdP-initiated SSO.
The SSO flow follows these steps:
  1. The user logs in to
    PAM
    and the Access page in the UI is displayed.
  2. On the Access page is a link to AWS Management Console Single Sign-On.
  3. The user selects the link and gains access to the Console directly without entering credentials.
SP-Initiated SSO to Google Apps
For SP-initiated communication, initiate the connection at the Google. Typically, the user has the access URL to the SP.
The following procedure describes a product that is independent of
CA Technologies
. The procedure is provided only as an example. You might encounter different features or appearance.
The SSO flow follows these steps:
  1. In a browser, the user enters the URL to Google: https://accounts.google.com/
  2. At the login, the user enters their user name.
  3. The SP redirects the user to the
    PAM
    IdP.
  4. If the user has not authenticated,
    PAM
    presents the login page. The user logs in and the IdP authenticates that user.
  5. Following authentication, the IdP redirects the user back to Google with the assertion. The user is logged in automatically to Google.