This guide is meant for people familiar with SAML and Active Directory who are trying to troubleshoot issues their users are seeing while using single sign-on (SSO). If you're just getting started with ADFS and Clever, take a look at the article on Setting up single sign-on (SSO) with ADFS. To identify issues in your single sign-on (SSO) Setup, view your district dashboard > Support Tools > Login Logs.
Normally, when a user selects 'Log in with ADFS', Clever will send the user out to your AD or other SAML server where they will enter their username and password. Clever never sees this username and password, but your server will redirect the user back to Clever with a token confirming the user logged in successfully. Clever will then "match" the user in your AD or other SAML system with a user in Clever, and log them into their app.
Unfortunately, in the real world errors do occur. Here are the common ones that we identify, and how to resolve them:
- The unique identifier passed to us from the SAML server did not match any user in Clever. In essence, a user (let's call her "Susan") was successfully able to prove who she was to the district's identity provider, but when the identity provider came to tell Clever "Hey, can you log Susan in for me?", we responded "Sorry, we don't have a Susan here". The most common cause of this is a user trying to log in that is not yet synced to Clever, but it could also be that the field we match on, say student number or email address, is missing in the SIS upload for the user in question. We show the matches we tried to make in your single sign-on (SSO) Event Logs, so check there and then look up the corresponding information in your SIS and/or Clever Data Browser to see what might be going on.
- This is pretty similar to "no_match" in that we couldn't find the user that tried to log in. In contrast to "no_match" though, "no_attributes" means that we didn't get any value at all that we could match on. For instance, say you are matching on email. If your server sent us "firstname.lastname@example.org" and we couldn't find that user, we'd throw a "no_match". If your server didn't send us any attributes at all, or if joe didn't have an email on the SAML server, then we won't get anything to match on, and we'll throw a "no_attributes". Check in their SAML server to see that the impacted user has all the right attributes, and also take a look at your claims rules to make sure all your claims rules are set up and map to valid attributes on your server.
- A somewhat misleading error message, but easy to solve. While technically correct, what this error really means is that you should check your claims rules and ensure that the "Name ID" attribute is set, as indicated in the Help Center docs.
- no_encrypted_assertion or signature_check_failed:
- This error indicates there is something wrong with how Clever and your SAML server talk securely. This may be an issue with the certificate on your server. We recommend verifying your SSL certification installation using this tool.
- A fairly rare error (hopefully!), and indicates that the status code we received back from your AD or SAML server was not a "success" status code. Often this is a rate-limiting issue, but it can also indicate your server is misconfigured, network is down, or another server bug. We recommend checking that your AD or SAML server is operational and responding to authentication requests.
- Unfortunately you encountered an error that we had never seen before. This should also be very rare, and if you ever run into one of these, please let us know.
If you have any questions, please reach out to Clever support! We are happy to help!