Configure SAML 2.0 Authentication (API)

Use the PAN-OS XML API to automate the configuration of SAML 2.0 single sign-on (SSO) and single logout (SLO). To configure SAML using the API, create scripts that import the SAML metadata file, create a SAML authentication profile, add users and user groups, and assign the authentication profile to firewall services. The following workflow provides an example of how to configure SAML using the XML API.
  1. (
    Recommended
    )
    Import a metadata file from the IdP
    The metadata file contains registration information and the certificate that the IdP uses to sign SAML messages. If you import a metadata file, you do not need to independently Create a SAML Identity Provider (IdP) server profile. Include the metadata file path and SAML server profile name in your GET request:
    • key
      : API key
    • file
      : file path to SAML metadata file. The metadata file contains registration information, as well as the certificate that the IdP uses to sign SAML messages. Export the metadata file from the IdP to a client system that the firewall can access. The certificate specified in the file must meet SAML requirements. Refer also to your IdP documentation for instructions.
    • profile-name
      : passphrase, up to 31 characters
    curl -k -F file=@filename.txt -g 'https://
    <firewall>
    /api/?key=apikey&type=import&category=idp-metadata&profile-name=
    <profilename>
    '
    If you perform this step, you can skip Step 2, Create a SAML Identity Provider (IdP) server profile.
  2. Create a SAML Identity Provider (IdP) server profile
    If you do not import a metadata file, include IdP configuration parameters in your GET request to create a SAML IdP server profile:
    • key
      : API key
    • vsys
      : location, example values: shared, vsys1, vsys2
    • name
      : server profile name
    • entity-id
      : identity provider id
    • certificate
      :
      (
      Best Practice
      )
      identity provider certificate
    • sso-url
      : identity provider SSO URL
    • slo-url:
      identity provider SLO URL
    • sso-binding:
      SSO SAML HTTP binding, acceptable values: post, redirect
    • ssl-binding:
      SSL SAML HTTP binding, acceptable values: post, redirect
    • max-clock-skew
      : difference in system time as measured in seconds between firewall and IdP. The default value is 60 with a range of 1-900.
    • validate-idp-certificate:
      (
      Best Practice
      )
      specify whether you want to validate the IdP certificate. The default value is yes.
    • want-auth-requests-signed
      : specify whether the IdP expects a digital signature on authentication requests. The default value is no.
    https://
    <firewall>
    /api/?key=
    <apikey>
    &type=config&action=set&xpath=/config/shared/server-profile/saml-idp/entry[@name='
    <server-profile-name>
    ']&element=<certificate><cert-name></certificate><entity-id><https://example.com/sso></entity-id><sso-url><https://example.com/sso></sso-url><sso-bindings><post></sso-bindings><slo-url><https://example.com/slo></slo-url><slo-bindings>post</slo-bindings><max-clock-skew><max-clock-skew></max-clock-skew><validate-idp-certificate><yes></validate-idp-certificate><want-auth-requests-signed><yes></want-auth-requests-signed>
  3. Create a SAML authentication profile using the PAN-OS XML API
    Include SAML authentication profile parameters in your GET request:
    • key
      : API key
    • authentication-profile:
      authentication profile name
    • enable-single-logout:
      specify whether you want to enable SAML single logout. The default value is no.
    • request-signing-certificate:
      request signing certificate name
    • server-profile:
      SAML Identity Provider (IdP) server profile name
    • certificate-profile:
      certificate profile name
    • attribute-name-username:
      SAML username attribute
    • attribute-name-usergroup:
      SAML user group attribute
    • attribute-name-access-domain:
      SAML admin domain attribute
    • attribute-name-admin-role:
      SAML admin role attribute
    https://
    <firewall>
    /api/?key=
    <apikey>
    &type=config&action=set&xpath=/config/shared/authentication-profile/entry[@name='
    <authentication-profile-name>
    ']/method/saml-idp&element=<enable-single-logout>no</enable-single-logout><request-signing-certificate><certificate-name></request-signing-certificate><server-profile><server-profile-name></server-profile><certificate-profile>profile-name</certificate-profile><attribute-name-username><username></attribute-name-username><attribute-name-usergroup><usergroup></attribute-name-usergroup><attribute-name-access-domain><access-domain></attribute-name-access-domain><attribute-name-admin-role><admin-role></attribute-name-admin-role>
  4. Add users and user groups that are allowed to authenticate with this authentication profile
    Include profile name and member list in your request:
    • key
      : API key
    • authentication-profile:
      authentication profile name
    • member
      : users or user groups. To include specific users or group, include them in brackets:
      [member1, member 3]
      . To include all users, include
      all
      .
    https://
    <firewall>
    /api/?key=
    <apikey>
    &type=config&action=set&xpath=/config/shared/authentication-profile/entry[@name='
    <authentication-profile-name>
    ']/allow-list&element=<member><all></member>
  5. Assign the authentication profile to firewall services that require authentication
    For example, to assign the authentication profile to a superuser administrator account for web access, include these parameters in your GET request:
    • key
      : API key
    • name
      : admin username
    • authentication-profile
      : name of the SAML authentication profile
    https://
    <firewall>
    /api/?key=
    <apikey>
    &type=config&action=set&xpath=/config/mgt-config/users/entry[@name='
    <adminname>
    ']&element=<permissions><role-based><superuser>yes</superuser></role-based></permissions><authentication-profile><authprofilename></authentication-profile>

Related Documentation