Follow

Single Sign-On

Populi supports SAML 2.0 single sign-on as either a Service Provider (SP) or Identity Provider (IdP).

  • When functioning as an identity provider, Populi accepts incoming authentication requests and provides a login page. When the user has successfully authenticated, Populi will redirect them back to your external application.
  • When functioning as a service provider, Populi won't store user passwords and will instead redirect users to your SAML 2.0 Identity Provider instead. Once the user has authenticated on your system, they will be redirected back to Populi where we will validate the response and then allow them access.
  • You cannot use Populi as both Identity Provider and Service Provider: it has to be either the authoritative source for user credentials or it has to look to an external system, but not both.
  • To set up SSO, you need to have Account Admin privileges to your school's Populi account.

Populi as a Service Provider (SP)

If you already maintain a SAML 2.0-compliant Identity Provider to authenticate students against your local network (Microsoft Active Directory Federation Services, for example), you can configure Populi to authenticate against your existing system.

  • SSO has no effect on a user's roles/permissions within Populi. It simply offloads to your system the decision about whether a particular login (username and password) is valid.
  • Also, if you block a user in Populi, Populi will deny him access and not even try to authenticate; therefore, you can disable a user's access to Populi without disabling him in your system.
  • The decision to set up Populi as a Service Provider should not be taken lightly. A misconfiguration on your end (in the Identity Provider) could allow anyone to log in to Populi—whether or not they should be able to! It can also block all access to Populi.
account_saml_sp

Service Provider Setup

This section includes instructions for configuring ADFS so it will be able to interact with Populi.

ADFS Setup

Here are the settings required on the ADFS end. Please refer to the ADFS app's documentation for further explanations and instructions.

  • Add a Relying Party Trust Wizard: Enter this information manually
  • Display name: Ditto
  • Select the AD FS Profile (1.0/1.1 do not work with SAML).
  • Check next to Enable support for the SAML 1.0 WebSSO protocol.
    • Copy-paste the URL from your Populi SSO page (e.g. https://yourschool.populiweb.com/router/saml/sp/metadata).
    • Add a Relying Party Trust. This must exactly match what is entered in the Service Provider Entity ID field in Populi (see below). The default is populiweb.com
  • In Claims:
    • Send LDAP attributes as Claims: Store: AD > LDAP attribute: E-Mail-Address to Outgoing claim type: E-Mail Address.
    • Transform an Incoming Claim: Incoming type: E-Mail Address to Outgoing Type: NameID. Format: Email
  • In Properties:
    • Monitoring tab: https://yourschool.populiweb.com/router/saml/sp/metadata
      Do not enable Monitor Relying party; Populi metadata is not compatible with monitoring.
    • Identifiers: populiweb.com
    • Endpoints > Add a SAML: Type: SAML Assertion Consumer; Binding: POST; SET AS DEFAULT: index 0; URL: https://yourschool.populiweb.com/router/saml/sp/consume
    • SHA-256

Populi Setup

  1. Go to Account > Account Settings > SSO (SP).
  2. Identity Provider URL: When a user attempts to log in, Populi will redirect their browser to this page, appending an unsigned SAML 2.0 <AuthnRequest> element to the URL and including the RelayState parameter set to your instance of Populi. This URL will vary depending on how you've set up your Identity Provider; check the documentation for whatever software you're using.
    • For ADFS, enter https://{adfs dns name}/adfs/ls/idpinitiatedsignon.aspx?logintoRP={trust name you choose in adfs}
  3. Sign-out URL: When a user logs out of Populi, where should we send them? Depending on your setup, this could be a sign-out URL that would destroy the session in your system that was created when the user logged in to Populi.
    • For ADFS, enter https://{adfs dns name}/adfs/ls/?wa=wsignout1.0
  4. Issuer: Enter the SAML entityID you chose when you set up your Identity Provider. If the issuer in your response doesn't match what you've entered in Populi, we won't allow the user to log in, so it's important to get this right.
    • For ADFS, enter https://{ adfs dns name }/adfs/services/trust
  5. Identity Provider Certificate: When your Identity Provider sends Populi an authentication response, we have to verify that it's you who sent it and not someone else. The SAML specification does this by requiring the Service Provider (Populi in this case) to have a copy of the Identity Provider's public key. The Identity Provider uses its private key to sign the request, and then the Service Provider can verify the signature because it has the Identity Provider's public key. Download your Identity Provider's public key as an X509 certificate.
    • For ADFS, export the certificate from ADFS > Service > Certificates as a Base-64 encoded X.509; then upload that to Populi.
  6. Service Provider Entity ID: When Populi sends a request to your identity provider, it needs to say who the request is from.By default, Populi identifies itself as "populiweb.com", but in some cases you'll need to change this—Azure, for example, requires the entity ID of all service providers to be a URL, so you could have Populi send requests using the entity ID https://populiweb.com instead. The entity ID is just an identifier used by your identity provider to match each request to the list of service providers it's been configured to support, so even if you use a URL, it doesn't have to point anywhere in particular (it just has to match what you set up in your identity provider).
    • For ADFS, enter the Relying Party Trust you choose when setting up ADFS; what you enter here must exactly match what you entered there!
  7. Enable Single Sign-on: Before you enable Single Sign-on, you must first Save your settings so we can validate your Identity Provider Certificate and confirm that the rest of your settings have been filled in.
    • When you check this box, SSO is active and all login requests will be routed to the URLs above. Please make sure everything is set up properly before you check this box!

Working with Azure?

You may find this Microsoft documentation helpful.

Troubleshooting

If you're having trouble, try pasting your raw SAML request into this SAML decoder tool. A common mistake is that the Issuer listed does not match what you have entered into Populi's Single Sign-On (SP) settings.

Important!

  • To aid in testing your SSO setup before you check this box (and possibly lock everyone out of Populi if it's not set up properly!), you can fill in and save the rest of your settings, then visit https://yourcollege.populiweb.com?sso=1. We won't actually allow you to log in until the Enable Single Sign-on box is checked, but we will redirect you to the Identity Provider URL and then show debugging information when you're redirected back to Populi after a successful login. Make sure you try this a few times and confirm that all your settings are correct before enabling SSO.
  • If at any time SSO breaks and you find yourself locked out of Populi, you can visit https://yourcollege.populiweb.com?sso=0 to bypass SSO and log in using your Populi credentials. As an account administrator, you can also reset key users' Populi passwords from their profile even while SSO is enabled. This will allow them to choose a Populi password that an be used to access Populi as described above if SSO breaks for some reason.
  • In order to access the API with Populi set up as a Service Provider, you must:
    1. Create the user account for making API calls in Populi before enabling SSO. If you already have SSO enabled, contact customer support for help in provisioning the user account.
    2. Bypass SSO when accessing the API. Your endpoint from which you will receive the access key will be https://yourcollege.populiweb.com/api/index.php?sso=0
    3. This snippet lets you test the connection by issuing a cURL POST: curl --data "username=username%40yourdomain.edu&password=_YOUR_URL_ENCODED_PASSWORD_" https://yourschool.populiweb.com/api/index.php?sso=0;

Populi as Identity Provider (IdP)

idp
  • If your application needs to authenticate against user accounts stored in Populi, use the metadata URL found at https://yourcollege.populiweb.com/router/saml/idp/metadata
  • Populi's IdP metadata (in XML format) can be .

    Its IdP certificate can be found at https://yourcollege.populiweb.com/router/account/sso_idp_cert.

  • If you want to use Google Apps for Education through Populi, our support team will set up Google Apps to use Populi as an Identity Provider as part of the integration.

Setup

To set up Populi as an IdP, you'll provide information about the service providers you wish to authenticate against Populi user accounts.

  1. Go to Account > Account Settings > SSO (SP).
  2. Under Should other applications be allowed to authenticate against Populi?, you have three options:
    • Never let other applications authenticate: This prevents Populi from being used as Identity Provider.
    • Always let other applications authenticate: Allows any application to authenticate against Populi.
    • Choose which applications can authenticate: Lets you specify service providers that can authenticate against Populi.
  3. When you select Always... or Choose..., you'll be given the option to Add a service provider.
    • Name: The name by which this service provider will be identified within Populi.
    • Entity ID: The same entity_ID as that of the service provider.
    • X509 Certificate: Copy-paste the certificate contents or leave this blank if you want to skip the identity check. If you are given an error message that the X509 certificate is not valid, then look for spaces in the certificate file and remove them! Some services will insert a space every 64 characters by default and those would need to be removed.
    • Consumer URLs: If you enter one URL per line, Populi will only send responses to these locations (this prevents man-in-the-middle attacks). This setting is ignored for signed requests, since in that case the SP's identity has already been verified.
    • Status: Is the application Active or Inactive?
  4. If desired, you can also use Advanced settings:
    • SAML Signature: Message Only (default), Assertion Only, or Message and Assertion
    • NameId Format: Email Address (default), Unspecified, Persistent, or Transient
    • NameId Template: This lets you exactly customize the format of the NameId sent back in the SAML replies. The default is {username}@domain
    • Logout Redirect URL: If you wish to redirect users somewhere else upon logging out, enter it here. Otherwise they will return to your school's Populi login page.
    • Custom Parameters: You may specify additional parameters to send back in the SAML reply with name and value. The following parameters are included by default: FirstName, LastName, Email, PopuliID, urn:oid:0.9.2342.19200300.100.1.3, and urn:oid:0.9.2342.19200300.100.1
  5. Finally, click Add service provider.
Was this article helpful?
1 out of 1 found this helpful
Have more questions? Submit a request

1 Comments

  • 0
    Avatar
    Roland Penner

    I had some trouble writing php code to decrypt the password. Using the mcrypt extention for php I was specifying MCRYPT_RIJNDAEL_256 as the algorithm. However decoding AES 256 requires using the MCRYPT_RIJNDAEL_128 alogrithm. (AES 256 simply means the key size is 256 bits or 32 characters).

    I figured this out after seeing error messages like "The IV parameter must be as long as the blocksize" in my event log. And then reading this article: http://www.chilkatsoft.com/p/php_aes.asp

Please sign in to leave a comment.