11.28. SAML-based Single Sign-On

This section will describe how to enable and use SAML single sign-on.

11.28.1. API Access for SAML

In dr-provision versions 4.8.0 and later, the DRP server provides two endpoints for enabling SAML Single Sign-On.

  • /login - Provides redirect endpoint for SAML workflow
  • /saml/list - Provides a list of possible identity providers

11.28.1.1. Login

By pointing a browser at https://drp-ip:api-port/login, the server will redirect the user to the identity provider for authentication. Once this is complete, the login page will return a token and info structure by default.

Additionally, the login endpoint uses two query parameters to provide additional customizations.

  • SAML-IDP=<IDP> - The IDP is the name of one of the configured Identity Providers.
  • redirect=<Base64 URL> - The redirect option takes a base64 encoded URL that should be redirected to upon success. A DRP token is appended to the URL as a query parameter.

11.28.1.2. List

By pointing a browser at https://drp-ip:api-port/saml/list, a list of SAML Identity Providers is returned. This is a smaller list from the Identity Provider objects. The object contains:

  • Name - the name of the IDP to use in the SAML-IDP query parameter
  • DisplayName - A display name to use for presenting to the user.
  • LogoPath - A path or URL to a logo image. If the PATH is a full URL, this will be an image. If the PATH is relative, the file is served from DRP files directory.

These fields map directly to the Identity Provider fields.

11.28.2. UX Access by SAML

The UX login page presents the standard authentication page. If Identity Providers have been configured and functional, the UX login page will have additional buttons for each of IDP. The UX will redirect the user to the SAML page for authentication. Upon completion, the UX is redirected to the UX system with a DRP token for normal operations.

11.28.3. Identity Provider Configuration

To enable SAML-based Single Sign-On, the system must have ONE or more Identity Provider configured. This configuration requires configuring the IDP with the DRP server’s metadata and vice versa.

The SAML Single Sign-On uses the API server’s certificate and key for identity. If this certificate/key pair is changed, the metadata at the IDP must be updated.

11.28.3.1. Register DRP with IDP

The DRP server must be registered with the IDP. The identity of the DRP server is first configured value in order:

  • Server Host Name
  • HA Id
  • DRP Id
  • Server Virtual IP
  • Server Static IP

With the identity established, registration be done one of two ways.

For some IDPs, they can be given a URL to get the metadata automatically. The metadata URL is https://drp-ip:api-port/saml/metadata. Entering this URL into the IDP will cause the IDP to query the DRP Server for the required certificate and identity information.

The other is to save the metadata into a file. This file will be XML data that can be upload to your identity provider.

curl -k https://drp-ip:api-port/saml/metadata -o metadata.xml

This metadata.xml file can be upload to your identity provider. The file can be reused for all Identity Providers.

11.28.3.2. Register IDP with DRP

This requires creating an Identity Provider in the DRP seystem. This can be either done through the UX or the CLI.

The required fields for the IDP are:

  • Name - this is the short name of the IDP.
  • DisplayName - this is the displayed name for us in the UX
  • LogoPath - this is an optional URL or relative file path into the DRP server. It presents an image for display.
  • MetaDataUrl - This the URL to the IDP’s metadata.
  • MetaDataBlob - This is the XML file from the IDP stored as a string on the object.

Upon loading into DRP or DRP startup, the Metadata is validated directly or URL is queried to get the data and validated.

Once both steps are done, SAML can be used for authentication.

11.28.3.3. Additional Customization

Each Identity Provider in DRP will also define the access control path for the authenticated users.

There are two attributes that are delivered by the SAML Assertions. The first attribute is used to define the username. This is the UserAttribute field. This maps the SAML IDP identity into the Name of a User. This is usually an email for ease of use, but is not required.

The second attribute is used to define groups that should apply to the user. This is the GroupAttribute field. The attribute in the SAML assertion should be a comma separated list of groups that the user is a member of.

The Identity Provider has three additional fields that control what access the user should have.

  • DenyIfNoGroups - If no groups are present or none match, access is denied that user.
  • DefaultRole - This is the default role that should be given to the User if no groups match. The DenyIfNoGroups overrides this.
  • GroupToRole - This is a map of group names to lists of roles. It is a key value pair, where the key is the group name and the value is a list of roles to apply.

An example yaml file for AWS:

---
DefaultRole: "superuser"
DenyIfNoGroups: false
DisplayName: AWS IAM
GroupAttribute: "groups"
GroupToRoles:
  role1:
    - operator
  role2:
    - superuser
MetaDataUrl: https://portal.sso.us-west-2.amazonaws.com/saml/metadata/Nzg0NDI0NjE0NTk2X2lucy03MjJmMGU0NjQ5OTRiNzNk
Name: aws-west-2
UserAttribute: "username"