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.

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 ADFS 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 a PEM-encoded X509certificate.
   • For ADFS, export the certificate from ADFS > Service > Certificates as a Base-64 encoded X.509; then upload that to Populi.
   • To check if you have the correct format, view your certificate as a text file. If the first line is -----BEGIN CERTIFICATE----- and the last line is -----END CERTIFICATE-----, you're in good shape!
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 or https://yourschool.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. Identity Provider Display Name: Enter a "friendly" name for the identity provider. This will be displayed to all users on the Populi login page if Automatic Login Redirection is disabled. The link will say Log in using _____, with the friendly name filling in the blank. If you enter nothing here, the link will say Log in using SSO. There is a 15-character limit for this setting!
8. Automatic Login Redirection: Enable this to redirect users to the Identity Provider’s login page without showing the Populi login page. This setting is ignored until SSO is enabled.
9. 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! Additionally, two new settings will appear:
   • Disable Populi welcome email for SSO users: Select “Yes” to disable the Populi-generated welcome email when creating a new SSO user. You can still manually override this when creating particular SSO users.
   • Login problem message: If users have trouble logging in to Populi, they will see a notice that a problem occured; customize this message using the text field.

Working with Azure?

We defer to Microsoft's documentation on Azure-related matters. That said, configuring these Azure settings as follows may expedite the setup on that side of the SSO setup.

• Reply URL: https://yourschool.populiweb.com
• Identity Provider URL: Login URL
• Sign-out URL: Logout URL
• Issuer: Azure AD Identifier
• Service Provider Entity ID: Application ID (Enterprise application)

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. Your endpoint from which you will receive the access key will be https://yourcollege.populiweb.com/api/index.php
  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

Populi as Identity Provider (IdP)

• If your application needs to authenticate against user accounts stored in Populi, use the metadata URL (in XML format) found at https://yourcollege.populiweb.com/router/saml/idp/metadata
• 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 (IdP).
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_IDas 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
urn:oid:0.9.2342.19200300.100.1
5. Finally, click Add service provider.