Adding a SAML identity provider



This topic discusses what's required of SAML IdPs in general and provides a step-by-step procedure for setting up a OneLogin IdP.

About adding a SAML identity provider

DC/OS Enterprise requires the SAML identity provider (IdP) to return an email attribute and sign the authentication assertion. The IdP must support urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress as a NameIDFormat. DC/OS receives this email value as an attribute from the IdP and uses it as a user ID.

While DC/OS Enterprise supports the full range of SAML 2.0 IdPs, the following procedure will take the OneLogin IdP as an example and provide step-by-step instructions.

Adding a OneLogin identity provider

Obtaining the identity provider metadata

  1. Log into the OneLogin dashboard as a OneLogin superuser.
  2. Create an IdP app that can send attributes and sign the auth assertion.
  3. Click to add the app.
  4. Type a descriptive name for this IdP in the Display Name field.
  5. Click Save.
  6. Click the SSO tab.
  7. Copy the Issuer URL value.
  8. Make a GET request to the Issuer URL from either a browser or using curl.
  9. It should return the identity provider XML.
<?xml version="1.0?>
<EntityDescriptor xmlns="urn:oasis:names:tc:SAML:2.0:metadata" entityID="">
  1. Copy the XML to a clipboard or into a text editor.

  2. Click the Access tab.

  3. Activate all roles you want to be able to log in to your cluster. For example: Employee and Engineer.

    Tip: Don’t click Save at this stage; it will fail.

Configuring DC/OS to act as a SAML service provider

  1. Log in to the DC/OS web interface as a user in the superuser group or with the dcos:superuser ACL.
  2. Open the System -> Organization -> Identity Providers tab.
  3. Click Add Provider.
  4. Click SAML 2.0.
  5. In the Provider ID field, type a name for your IdP that can be passed in a URL. This can be any name unless you have more than one SAML IdP. If you have another SAML IdP, you must pick a different name for this one. Example: my-saml-idp.
  6. Type a descriptive name for the IdP in the Description field. This name should allow you to find it in a list of IdPs later on. Example: SAML IdP.
  7. Paste the identity provider XML metadata obtained in the previous section into the IDP Metadata field.
  8. Copy the URL in the top of your browser, everything before the first slash, and paste it into the Service Provider Base URL field.
  9. Click Submit.

Obtain the DC/OS callback URL

Tip: This procedure uses the Identity and Access Management API (IAM API). For more details on the IAM API, you can visit the IAM API documentation.

  1. Make a GET request to <your-cluster-URL>/acs/api/v1/auth/saml/providers using either your browser or curl.

  2. It will return a JSON object containing the provider IDs and descriptions of each identity provider you have configured.

      "my-saml-idp": "SAML IdP"
  3. Locate your identity provider in the list and copy its provider ID to your clipboard or a text editor. In the previous example, the provider ID is my-saml-idp.

  4. Make a GET request to <your-cluster-URL>/acs/api/v1/auth/saml/providers/{provider-id}/acs-callback-url, replacing {provider-id} with the provider ID you obtained in the previous step.

  5. This request returns the callback URL.

      "acs-callback-url": ""
  6. Copy this value to your clipboard or a text editor.

Provide the OneLogin identity provider with the callback URL

  1. Click to open the Configuration tab in the OneLogin dashboard.
  2. Paste the callback URL obtained in the previous procedure into the following three fields: Recipient, ACS (Consumer) URL Validator, and ACS (Consumer) URL.
  3. Paste your cluster URL into the Audience field. Append the following to it: /acs/api/v1/auth/saml/providers/{provider-id}/sp-metadata.
  4. Replace {provider-id} with your provider ID. Example,
  5. Click Save.

Verify the connection

  1. Clear your cookies or start a new browser session.

  2. Navigate to the login page of the DC/OS web interface.

  3. Click on the button of the SAML provider you just configured.

  4. You should receive an “Access denied” message from DC/OS.

    Note: This indicates that DC/OS verified your account with the third party provider and imported it into DC/OS. Since your account has no permissions by default, it returns “Access denied.”

Assign permissions

  1. Log into the DC/OS web interface using an account with superuser privileges.
  2. Locate the email address of the user you just tried to log in as in the System -> Organization -> Users tab and double-click it.
  3. Assign the desired permissions to the account. For more information about assigning permissions, visit the Permissions documentation.