Skip to content

Instantly share code, notes, and snippets.

@oddlyfunctional

oddlyfunctional/SAML.md

Created June 20, 2019 06:53
Show Gist options
  • Save oddlyfunctional/cbb524d005fb4fd74b2ee61bcebc6fc6 to your computer and use it in GitHub Desktop.
Save oddlyfunctional/cbb524d005fb4fd74b2ee61bcebc6fc6 to your computer and use it in GitHub Desktop.
Download ZIP
Raw
SAML.md

Adding a new identity provider

  1. Make sure the org has an entry in org_domain
  2. Prepare the configuration for passport-saml, all keys are accepted, but the minimum necessary are: idpIssuer (idP's ID), entryPoint (idP's endpoint for sending SAML requests), cert (idP's public certificate) and callbackUrl (Coursebase's endpoint for the SAML response).
  3. Serialize the configuration object with JSON.stringify(config) (if you'll copy and paste, make sure to do it on node environment since the browser can print the serialized strings with some escaping issues). For example:
let config = {
  idpIssuer: "https://app.onelogin.com/saml/metadata/c7ad6f53-52e0-4ff1-996c-3222c0850812",
  entryPoint: "https://greyhound-dev.onelogin.com/trust/saml2/http-redirect/sso/930729",
  cert: "-----BEGIN CERTIFICATE-----\\nMIID4jCCAsqgAwIBAgIUAipD1o1iXRi/BVk4iHeBGhei+S4wDQYJKoZIhvcNAQEF\\nBQAwRzESMBAGA1UECgwJR3JleWhvdW5kMRUwEwYDVQQLDAxPbmVMb2dpbiBJZFAx\\nGjAYBgNVBAMMEU9uZUxvZ2luIEFjY291bnQgMB4XDTE5MDUwNzA3NDQ0NFoXDTI0\\nMDUwNzA3NDQ0NFowRzESMBAGA1UECgwJR3JleWhvdW5kMRUwEwYDVQQLDAxPbmVM\\nb2dpbiBJZFAxGjAYBgNVBAMMEU9uZUxvZ2luIEFjY291bnQgMIIBIjANBgkqhkiG\\n9w0BAQEFAAOCAQ8AMIIBCgKCAQEAvMe7BQXGxUf0JbPYgrNfQzuf2NoZTnHvpJuv\\nfDUc1KjXnzbuX6fNvG06vbtimdbI95sV8GkTspNiDO3Sz/VQEurG/rE54BG1dQEf\\nKjPcg8RJAfgC+UzSr9qsTQrDI+57g58YwDqM+GIXf5OAVeRdv2vQbtLTg55SBtCR\\nERwfd4rG1qpJRHLZ7FlI/HRUSmd82bgdBxjFqwB6Zmqr1D3iimmjl/BYX+N6SLIv\\nH42LFNZbvzQtnAt61PTOhLpLUJ5ZSQwh++c3TpraRlDSxX38c89kYGiHUfbrAObH\\nhgt7EBSCWm9cQhezDx9UHSOd0lHRdUkKmPaWfDQ0HeCXvaaUgQIDAQABo4HFMIHC\\nMAwGA1UdEwEB/wQCMAAwHQYDVR0OBBYEFN58AGuCqrs4KwcjeiMMvnK8qw4NMIGC\\nBgNVHSMEezB5gBTefABrgqq7OCsHI3ojDL5yvKsODaFLpEkwRzESMBAGA1UECgwJ\\nR3JleWhvdW5kMRUwEwYDVQQLDAxPbmVMb2dpbiBJZFAxGjAYBgNVBAMMEU9uZUxv\\nZ2luIEFjY291bnQgghQCKkPWjWJdGL8FWTiId4EaF6L5LjAOBgNVHQ8BAf8EBAMC\\nB4AwDQYJKoZIhvcNAQEFBQADggEBAJtya4X8z3QRiRzQPYvILj2zHl4uEJ1IDuKi\\nQIkOW7lmKSQ6N6GR13ZjVPqStBWNNeGsbSuslbQrR92hjikvPGumkhfPvWTzITci\\nbSp7Cmbtkie8+uwK7OfIi6N+5MVWvl81vhJqUsbQ9JvHhvRk+reCj4Tv8p+f0hnv\\ncgc6Js2UQtYeXckVmLow1ScjbsL4Iddh0Vb14SiYo7eBqGbFyEE0ZLeZXi73OhuF\\nrUmFduShdGfyGHFhxBi0QI44jiTD3ls7/kKbTw0UsPa5+RPh3NRcpTd5nVKPq3X6\\nqiuGjkPDvWpx3l83SHBRijBQb0pKwn7uXK0U5kzF/SPb8sqw4wg=\\n-----END CERTIFICATE-----",
  callbackUrl: "http://127.0.0.1:3000/v2/sso/consume"
};

JSON.stringify(config) == '{"idpIssuer":"https://app.onelogin.com/saml/metadata/c7ad6f53-52e0-4ff1-996c-3222c0850812","entryPoint":"https://greyhound-dev.onelogin.com/trust/saml2/http-redirect/sso/930729","cert":"-----BEGIN CERTIFICATE-----\\\\nMIID4jCCAsqgAwIBAgIUAipD1o1iXRi/BVk4iHeBGhei+S4wDQYJKoZIhvcNAQEF\\\\nBQAwRzESMBAGA1UECgwJR3JleWhvdW5kMRUwEwYDVQQLDAxPbmVMb2dpbiBJZFAx\\\\nGjAYBgNVBAMMEU9uZUxvZ2luIEFjY291bnQgMB4XDTE5MDUwNzA3NDQ0NFoXDTI0\\\\nMDUwNzA3NDQ0NFowRzESMBAGA1UECgwJR3JleWhvdW5kMRUwEwYDVQQLDAxPbmVM\\\\nb2dpbiBJZFAxGjAYBgNVBAMMEU9uZUxvZ2luIEFjY291bnQgMIIBIjANBgkqhkiG\\\\n9w0BAQEFAAOCAQ8AMIIBCgKCAQEAvMe7BQXGxUf0JbPYgrNfQzuf2NoZTnHvpJuv\\\\nfDUc1KjXnzbuX6fNvG06vbtimdbI95sV8GkTspNiDO3Sz/VQEurG/rE54BG1dQEf\\\\nKjPcg8RJAfgC+UzSr9qsTQrDI+57g58YwDqM+GIXf5OAVeRdv2vQbtLTg55SBtCR\\\\nERwfd4rG1qpJRHLZ7FlI/HRUSmd82bgdBxjFqwB6Zmqr1D3iimmjl/BYX+N6SLIv\\\\nH42LFNZbvzQtnAt61PTOhLpLUJ5ZSQwh++c3TpraRlDSxX38c89kYGiHUfbrAObH\\\\nhgt7EBSCWm9cQhezDx9UHSOd0lHRdUkKmPaWfDQ0HeCXvaaUgQIDAQABo4HFMIHC\\\\nMAwGA1UdEwEB/wQCMAAwHQYDVR0OBBYEFN58AGuCqrs4KwcjeiMMvnK8qw4NMIGC\\\\nBgNVHSMEezB5gBTefABrgqq7OCsHI3ojDL5yvKsODaFLpEkwRzESMBAGA1UECgwJ\\\\nR3JleWhvdW5kMRUwEwYDVQQLDAxPbmVMb2dpbiBJZFAxGjAYBgNVBAMMEU9uZUxv\\\\nZ2luIEFjY291bnQgghQCKkPWjWJdGL8FWTiId4EaF6L5LjAOBgNVHQ8BAf8EBAMC\\\\nB4AwDQYJKoZIhvcNAQEFBQADggEBAJtya4X8z3QRiRzQPYvILj2zHl4uEJ1IDuKi\\\\nQIkOW7lmKSQ6N6GR13ZjVPqStBWNNeGsbSuslbQrR92hjikvPGumkhfPvWTzITci\\\\nbSp7Cmbtkie8+uwK7OfIi6N+5MVWvl81vhJqUsbQ9JvHhvRk+reCj4Tv8p+f0hnv\\\\ncgc6Js2UQtYeXckVmLow1ScjbsL4Iddh0Vb14SiYo7eBqGbFyEE0ZLeZXi73OhuF\\\\nrUmFduShdGfyGHFhxBi0QI44jiTD3ls7/kKbTw0UsPa5+RPh3NRcpTd5nVKPq3X6\\\\nqiuGjkPDvWpx3l83SHBRijBQb0pKwn7uXK0U5kzF/SPb8sqw4wg=\\\\n-----END CERTIFICATE-----","callbackUrl":"http://127.0.0.1:3000/v2/sso/consume"}';
  1. Prepare the translation object for the login button. It should be in the form { [language]: { t: translation } }, for example { pt: { t: "Entrar com SAML" }, ja: { t: "SAMLログイン" } }.
  2. Serialize it with JSON.stringify(translations) (taking the same precautions as when serializing the passport-saml config).
  3. Insert into the org_saml table (notice that the issuer column must match the idpIssuer property in the passport-saml config object):
INSERT INTO org_saml (org_id, issuer, required, login_label, login_label_tr, config) VALUES (
  4,
  'https://app.onelogin.com/saml/metadata/c7ad6f53-52e0-4ff1-996c-3222c0850812',
  0,
  'Login with SAML',
  '{"pt":{"t":"Entrar com SAML"},"ja":{"t":"SAMLログイン"}}',
  '{"idpIssuer":"https://app.onelogin.com/saml/metadata/c7ad6f53-52e0-4ff1-996c-3222c0850812","entryPoint":"https://greyhound-dev.onelogin.com/trust/saml2/http-redirect/sso/930729","cert":"-----BEGIN CERTIFICATE-----\\\\nMIID4jCCAsqgAwIBAgIUAipD1o1iXRi/BVk4iHeBGhei+S4wDQYJKoZIhvcNAQEF\\\\nBQAwRzESMBAGA1UECgwJR3JleWhvdW5kMRUwEwYDVQQLDAxPbmVMb2dpbiBJZFAx\\\\nGjAYBgNVBAMMEU9uZUxvZ2luIEFjY291bnQgMB4XDTE5MDUwNzA3NDQ0NFoXDTI0\\\\nMDUwNzA3NDQ0NFowRzESMBAGA1UECgwJR3JleWhvdW5kMRUwEwYDVQQLDAxPbmVM\\\\nb2dpbiBJZFAxGjAYBgNVBAMMEU9uZUxvZ2luIEFjY291bnQgMIIBIjANBgkqhkiG\\\\n9w0BAQEFAAOCAQ8AMIIBCgKCAQEAvMe7BQXGxUf0JbPYgrNfQzuf2NoZTnHvpJuv\\\\nfDUc1KjXnzbuX6fNvG06vbtimdbI95sV8GkTspNiDO3Sz/VQEurG/rE54BG1dQEf\\\\nKjPcg8RJAfgC+UzSr9qsTQrDI+57g58YwDqM+GIXf5OAVeRdv2vQbtLTg55SBtCR\\\\nERwfd4rG1qpJRHLZ7FlI/HRUSmd82bgdBxjFqwB6Zmqr1D3iimmjl/BYX+N6SLIv\\\\nH42LFNZbvzQtnAt61PTOhLpLUJ5ZSQwh++c3TpraRlDSxX38c89kYGiHUfbrAObH\\\\nhgt7EBSCWm9cQhezDx9UHSOd0lHRdUkKmPaWfDQ0HeCXvaaUgQIDAQABo4HFMIHC\\\\nMAwGA1UdEwEB/wQCMAAwHQYDVR0OBBYEFN58AGuCqrs4KwcjeiMMvnK8qw4NMIGC\\\\nBgNVHSMEezB5gBTefABrgqq7OCsHI3ojDL5yvKsODaFLpEkwRzESMBAGA1UECgwJ\\\\nR3JleWhvdW5kMRUwEwYDVQQLDAxPbmVMb2dpbiBJZFAxGjAYBgNVBAMMEU9uZUxv\\\\nZ2luIEFjY291bnQgghQCKkPWjWJdGL8FWTiId4EaF6L5LjAOBgNVHQ8BAf8EBAMC\\\\nB4AwDQYJKoZIhvcNAQEFBQADggEBAJtya4X8z3QRiRzQPYvILj2zHl4uEJ1IDuKi\\\\nQIkOW7lmKSQ6N6GR13ZjVPqStBWNNeGsbSuslbQrR92hjikvPGumkhfPvWTzITci\\\\nbSp7Cmbtkie8+uwK7OfIi6N+5MVWvl81vhJqUsbQ9JvHhvRk+reCj4Tv8p+f0hnv\\\\ncgc6Js2UQtYeXckVmLow1ScjbsL4Iddh0Vb14SiYo7eBqGbFyEE0ZLeZXi73OhuF\\\\nrUmFduShdGfyGHFhxBi0QI44jiTD3ls7/kKbTw0UsPa5+RPh3NRcpTd5nVKPq3X6\\\\nqiuGjkPDvWpx3l83SHBRijBQb0pKwn7uXK0U5kzF/SPb8sqw4wg=\\\\n-----END CERTIFICATE-----","callbackUrl":"http://127.0.0.1:3000/v2/sso/consume"}'
);

Configuring identity provider to accept Coursebase requests

Everything you need to configure the identity is in our metadata XML: /v2/sso/metadata.xml. For example, in develop, the XML is in https://api.coursebase.xyz/v2/sso/metadata.xml. Usually the values needed are the EntityDescriptor.entityID, the ds:X509Certificate and the AssertionConsumerService.Location. Please download the file file to your filesystem; it'll make the configuration easier.

For demonstration, let's setup a new Microsoft Azure Active Directory identity provider (we'll skip signing up for the service):

  1. Open https://portal.azure.com.
  2. Click on "Azure Active Directory".
  3. In the new sidebar, in the "Manage" section, click on "Enterprise applications" (you may need to have a verified account to do that).
  4. Click on "+ New application" and select "Non-gallery application".
  5. Input a name to your application (e.g. "Test Application"), click "Add" and wait for the operation to complete (it takes a while and the UI doesn't provide a lot of feedback).
  6. You should now be in "Home > Enterprise applications - All applications > Categories > Add an application > Test Application - Overview".
  7. In the new sidebar, in the "Manage" section, click on "Single Sign-on" and in the "Select a single sign-on method" screen select "SAML".
  8. You should now be in "Home > Test Application - Single sign-on > SAML-based sign-on".
  9. In the page's top menu, click on "Upload metadata file", select the metadata you saved from Coursebase and add it.
  10. A form will show up to make sure the uploaded values are correct. Ensure the Entity ID (unfortunately there can't be two applications with the same Entity ID in the same Azure organization) and the Assertion Consumer Service match the values in our metadata. Click "Save".
  11. Now, in "Home > Test Application - Single sign-on > SAML-based sign-on", on the "User Attributes & Claims" section, click on the edit button.
  12. Click "+ Add new claim".
  13. Fill the form as such: Name = email, Namespace = empty, Source = Attribute, Source attribute = user.mail. Click "Save".
  14. In the "SAML Signing Certificate" section, download the "Certificate (Base64)" file. The content of this file will be the cert property in the passport-saml config object.
  15. In the "Set up Test Application" section, copy the "Login URL". This will be the entryPoint in the passport-saml config object.
  16. In the "Set up Test Application" section, copy the "Azure AD Identifier". This will be the idpIssuer in the passport-saml config object and the issuer column in the org_saml row.

All done!

Adding a new user to the identity provider

  1. Ensure the user is added to the Coursebase database before moving forward.
  2. Open https://portal.azure.com.
  3. Click on "Azure Active Directory".
  4. In the new sidebar, in the "Manage" section, click on "Enterprise applications".
  5. Find the application you want to add the user to (e.g. "Test Application") and click on its name.
  6. In the new sidebar, in the "Manage" section, click on "Users and groups".
  7. You should now be in "Home > Enterprise applications - All applications > test - Users and groups".
  8. Click "+ Add new user".
  9. In the "Add Assignment" sidebar, select "Users and groups"
  10. In the "Users and groups" sidebar, in the search box, input the user's email (must match the email in the Coursebase database).
  11. If the user already exists in the Azure organization, you can just click on it, then in the "Select" button (multiple users can be added at the same time). If not, first click on "Invite", then on "Select". It's very important that you wait for the invitation to be successfully sent before clicking on "Select". You will know the user was successfully invited if he shows up in the "Selected members:" section.
  12. After clicking on select, in the "Add Assignment" sidebar, make sure under the "Users and groups" option it shows "1 user selected". If yes, click on the "Assign" button.
  13. The invitation will be sent to the email, and the user must complete the registration.
  14. Wait a few minutes before trying to login using SAML in Coursebase since it takes a while for all changes to be applied.

All done!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment