Skip to content

Latest commit

 

History

History
130 lines (108 loc) · 9.08 KB

saml.md

File metadata and controls

130 lines (108 loc) · 9.08 KB

SAML Single Sign On

The GrayMeta Platform supports SP initiated SAML logins and has been tested against the following identity providers:

  • Okta
  • Azure AD
  • onelogin

IMPORTANT NOTE: Before enabling SAML, please deploy the platform as described in the main README, log into the platform with the [email protected] account, create at least one account that uses an email address that is the same as an email address associated with a user in your identity provider. This new account needs to be assigned the super-user role as once SAML is enabled the local [email protected] account will no longer be able to authenticate.

Enabling SAML

Before we begin, you must know the URL that your site is deployed at. If you set the dns_name variable in the Terraform configuration to foo.example.com, your endpoint url (from now on referenced as endpoint) will be https://foo.example.com.

Various URLs that you will need:

  • Assertion Consumer Service (ACS) URL: {endpoint}/saml/acs - also referred to as the Reply URL.
  • Audience URI (SP Entity ID): {endpoint}/saml/metadata

OKTA Procedure

  1. Create an application in your IDP.

  2. Configure your SAML IDP with the ACS URL and Audience URI/SP Entity ID URLs.

  3. Configure the following attribute statements. Note that these are based on Okta, but adjust as necessary for your IDP:

    • uid: user.id Unique id for every user
    • firstname: user.firstName
    • lastname: user.lastName
    • email: user.email

    If you can't name an attribute exactly as specified (for example if you can't name firstname as firstname, set the saml_attr_{attribute} variable to the name of the attribute. For example, if I couldn't name the uid attribute and the IDP set it as uniqueidentifier, then set the saml_attr_uid variable in the platform section of the terraform configration to the value uniqueidentifier.

  4. Assign users in your IDP to the application.

  5. Take a note of the application's Identity Provider metadata URL and add it to the platform section of your Terraform configuration as the saml_idp_metadata_url variable. For Okta this URL is under Sign On -> Settings and looks like https://dev-855992.okta.com/app/exk1h5wz8k64AyA6F357/sso/saml/metadata

  6. Generate a self-signed x509 certificate:

    openssl req -x509 -newkey rsa:2048 -keyout myservice.key -out myservice.cert -days 365 -nodes -subj "/CN=myservice.example.com"

    NOTE: the CN of the certificate doesn't matter.

  7. base64 encode the certificate:

    cat myservice.cert | base64 -w0

    Add this string to the platform section of your Terraform configuration as the saml_cert variable. If you are using the encrypted blob, feel free to add this information to that configuration instead: saml_cert={base64 encoded cert}.

  8. base64 encode the key:

    cat myservice.key | base64 -w0

    Add this string to the platform section of your Terraform configuration as the saml_key variable. If you are using the encrypted blob, feel free to add this information to that configuration instead: saml_key={base64 encoded key}.

  9. Run a terraform apply and browse to your {endpoint} URL. You should be redirected to your IDP's login screen to begin the authentication process. If you are not redirected and instead are dropped into the application, you may still be logged in as the [email protected] account. If that is the case, click the logout button and you should get redirected to your IDP login screen.

Azure AD Procedure

  1. Create an Enterprise App using the Integrate any other application you don't find in the gallery option, then proceed to configure SSO/SAML.

  2. Set the Identifier (Entity ID) as {endpoint}/saml/metadata

  3. Set the Reply URL (Assertion Consumer Service URL) as {endpoint}/saml/acs

  4. Configure Single Sign-On with SAML in the Azure portal with the following attribute statements, and set your variables in Terraform:

    • saml_attr_email = "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress" (user.mail)
    • saml_attr_firstname = "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname" (user.givenname)
    • saml_attr_lastname = "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname" (user.surname)
    • saml_attr_uid = "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier" (user.objectid)

  5. Add the 'App Federation Metadata Url' to the saml_idp_metadata_url variable.

  6. Generate a self-signed x509 certificate:

    openssl req -x509 -newkey rsa:2048 -keyout myservice.key -out myservice.cert -days 365 -nodes -subj "/CN=myservice.example.com"

    NOTE: the CN of the certificate doesn't matter.

  7. base64 encode the certificate:

    cat myservice.cert | base64 -w0

    Add this string to the platform section of your Terraform configuration as the saml_cert variable. If you are using the encrypted blob, feel free to add this information to that configuration instead: saml_cert={base64 encoded cert}.

  8. base64 encode the key:

    cat myservice.key | base64 -w0

    Add this string to the platform section of your Terraform configuration as the saml_key variable. If you are using the encrypted blob, feel free to add this information to that configuration instead: saml_key={base64 encoded key}.

  9. Run a terraform apply and browse to your {endpoint} URL. You should be redirected to your IDP's login screen to begin the authentication process. If you are not redirected and instead are dropped into the application, you may still be logged in as the [email protected] account. If that is the case, click the logout button and you should get redirected to your IDP login screen.

onelogin Procedure

  1. Create an App in the onelogin console using the SAML Test Connector (Advanced) template.

  2. Enter the following configurations in the App Configuration tab:

    Field Value
    Audience (EntityID) {endpoint}/saml/metadata
    Recipient {endpoint}/saml/acs
    ACS (Consumer) URL Validator* {endpoint}/saml/acs
    ACS (Consumer) URL* {endpoint}
    SAML initiator OneLogin
    SAML nameID format Unspecified
    SAML Issuer type Generic
    SAML signature element Assertion

    All other default fields can be left blank or unchanged.

  3. Add the following changes/additions to your App Parameters tab:

    • Change NameID Value to - No default –
    • Add the Field name “email”, click “include in SAML assertion”, set the value to “Email”
    • Add the Field name “firstname”, click “include in SAML assertion”, set the value to “First Name”
    • Add the Field name “lastname”, click “include in SAML assertion”, set the value to “Last Name”
    • Add the Field name “uid”, click “include in SAML assertion”, set the value to “OneLogin ID”

  4. Retrieve the SAML IDP Metedata URL from your App by clicking the More Actions button, then right-click on the SAML Metadata option and copy the link address. Add this URL to your terraform.tfvars file under (Optional) SAML Configuration as the saml_idp_metadata_url variable.

  5. Set the following your variables to your terraform.tfvars file under (Optional) SAML Configuration:

    • saml_attr_email = "email"
    • saml_attr_firstname = "firstname"
    • saml_attr_lastname = "lastname"
    • saml_attr_uid = "uid"

  6. Generate a self-signed x509 certificate:

    openssl req -x509 -newkey rsa:2048 -keyout myservice.key -out myservice.cert -days 365 -nodes -subj "/CN=myservice.example.com"

    NOTE: the CN of the certificate doesn't matter.

  7. base64 encode the certificate:

    cat myservice.cert | base64 -w0

    Add this string to your terraform.tfvars file under (Optional) SAML Configuration as the saml_cert variable. If you are using the encrypted blob, feel free to add this information to that configuration instead: saml_cert={base64 encoded cert}.

  8. base64 encode the key:

    cat myservice.key | base64 -w0

    Add this string to your terraform.tfvars file under (Optional) SAML Configuration as the saml_key variable. If you are using the encrypted blob, feel free to add this information to that configuration instead: saml_key={base64 encoded key}.

  9. Run a terraform apply and browse to your {endpoint} URL. You should be redirected to your IDP's login screen to begin the authentication process. If you are not redirected and instead are dropped into the application, you may still be logged in as the [email protected] account. If that is the case, click the logout button and you should get redirected to your IDP login screen.