Configuring Shibboleth and Canvas Authentication

Document created by jivedocs@instructure.com Employee on Jun 29, 2015Last modified by Karli Woolley on Jul 6, 2017
Version 15Show Document
  • View in full screen mode

    Official Canvas Document

Canvas + Logo transparent (WHITE)- 300px.png

 

 

Background

Single Sign On (SSO) is a functionality that many schools will configure during the implementation phase of transitioning to Canvas online with their institution. SSO provides many benefits, not the least being that after users sign in to one of the services at an institution they are automatically authenticated into any other service that uses SSO. The user is only required to remember one set of credentials. Shibboleth is a superset of SAML 2.0, which supports SSO. Shibboleth includes specifications for discovery, federation, artifact resolution etc.

 

Canvas can consume SAML 2.0 identity assertions. Canvas does not support the full Shibboleth protocol specifications, but can consume SAML 2.0 assertions originating from an appropriately configured Shibboleth (the product) identity provider.

 

When Canvas receives a successful identity assertion from any of it's supported authentication integrations, it searches for a user "login_id" that matches the value of the asserted identity. If it finds a matching login_id, it logs in the associated user account.

 

For example, if Canvas receives a SAML 2.0 assertion for a user and the value for the configured identity attribute is "fred," Canvas will search for a user with a login_id of "fred." If one is found, the associated user is logged in; otherwise the login is unsuccessful.

 

Administrators can view/modify/create login credentials for users by clicking on the user account name in the search results for users. The search for user will search for email, SIS identifier, login username, etc.

 

This article describes the process of configuring Shibboleth to work with Canvas.

 

Authentication Workflow

SAML Workflow Final.jpg

Authentication Terminology

 

TermDefinition
SAMLSecurity Assertion Markup Language
IdPIdentity Provider.
The job of the IdP is to identify users based on credentials.  The IdP typically provides the login screen interface and presents information about the authenticated user to Service Providers after successful authentication.
Shibboleth is the Identity Provider.
SPService Provider.
An SP is usually a website providing information, tools, reports, etc to the end user.  Canvas provides a learning environment to teachers, students, and admins and is therefore the Service Provider.
Note: An SP cannot authenticate against an IdP unless the IdP is known to the SP.  Likewise, an IdP will not send assertions to an SP that it does now know about.
MetadataInformation about the SP or IdP.  This metadata is almost always provided in the form of XML.  The metadata about your Canvas instance is located at https://<yourcanvas>.instructure.com/saml2 (replace <yourcanvas> with the first portion of your Canvas domain).
SSOSingle Sign On.
This is what happens when a user isn't required to log in to a second service because information about the authenticated user is passed to the service.
SLOSingle Logout.
When a user logs out of a service, some IdPs can subsequently log the user out of all other services the user has authenticated to. 
Shibboleth does not natively supports this. Read more at https://wiki.shibboleth.net/confluence/display/SHIB2/IdPEnableSLO.
login_idUsername in Canvas terminology.
When information about an authenticated user is returned to Canvas, a user with a login_id matching the incoming data is looked for.
SIS IDUnique ID of a user in Canvas.
Used to link a user to an outside system, often a Student Information System (SIS).
SISStudent Information System

 

Prerequisites

  • Any user that needs to authenticate via Shibboleth must already have a user account provisioned in Canvas.
  • The login_id field in Canvas must match the username field returned from Shibboleth.
  • Canvas does not automatically create user accounts from successful single-sign-ons. User accounts must either be created manually in the web interface or through the SIS import CSVs.
  • Shibboleth must be installed and running before completing this guide. Please refer to https://wiki.shibboleth.net/confluence/display/SHIB2/Installation for more information on setting up Shibboleth.

 

Test and Beta Canvas Sites

Each Canvas account comes with a .test and .beta site.  Information about these sites is described in detail elsewhere. You will want to test your authentication setup in the test area first before moving to production.


Note: The Canvas metadata contains AssertionConsumerService URLs for each of the production, test, and beta environments.  With a single entity ID, there may be some confusion around how to configure the IdP to work for these three seemingly separate areas.  You should consider all three together as a single Service Provider with a single Entity ID with three possible AssertionConsumerService URLs.


Shibboleth is built to handle this natively so this should not create any problems.  Once you configure Shibboleth to contain your school's metadata, Shibboleth will be able to do authentication with production, test, and beta. Many IdP's do not have the ability to work with multiple AssertionConsumerService URLs in the metadata.

 

Login Release Valve

You may lock yourself out of Canvas while you are working setup authentication.  If this happens, there is a way to log in to Canvas using local authentication.  Simply go to /login/canvas. For instance: http://<yourcanvasname>.instructure.com/login/canvas (This forces Canvas to display the local login form rather than redirecting to the SAML login page).

 

Institutions using LDAP or SAML authentication can now use the same authentication to register observers in Canvas. For LDAP institutions, observers will enter the student's LDAP credentials directly from the registration page. For SAML institutions, observers will be redirected to the authentication page and log in with the credentials of the student they are observing. This authentication process is also used when observers add additional observees to their accounts.

 

Shibboleth must be installed and running before following these steps.

 

Configuring Shibboleth with Canvas

Configuring Shibboleth and Canvas to work together involves the following steps:

  1. Configure Shibboleth with Canvas Metadata
  2. Configure Canvas to Know about Shibboleth IdP(s)

 

Configure Shibboleth with Canvas Metadata

Reminder: These instructions may need to be translated to your specific installation and configuration.  You should specifically note that the file paths may be different on your system.

 

Calculate Certificate Fingerprint On the IdP

OpenSSL will calculate the X.509 certificate fingerprint needed. If your certificate file

is named idp.crt run:

 

openssl x509 -noout -in idp.crt -fingerprint

 

In Shibboleth 2, this may be located in /opt/shibboleth-idp/credentials/idp.crt. If not, you should review your Shibboleth configuration to locate the correct certificate.

 

Obtain Canvas Metadata

Metadata for your Canvas account is located at https://<yourcanvas>.instructure.com/saml2

 

Adjust IdP Configuration Files

Remember to change as needed for your own particular situation.

 

Edit relying-party.xml to add Canvas SP metadata

 

Edit your /etc/shibboleth-idp/relying-party.xml file to let your IdP know about the Canvas SP.

 

Here is a sample configuration:

 

<metadata:MetadataProvider id="canvas" xsi:type="FileBackedHTTPMetadataProvider"

xmlns="urn:mace:shibboleth:2.0:metadata" metadataURL="https://yourschool.instructure.com/saml2"
backingFile="/opt/shibboleth-idp/metadata/canvas-metadata-bak.xml"></metadata:MetadataProvider>


Edit attribute-resolver.xml to resolve a NameID

Edit your /etc/shibboleth-idp/attribute-resolver.xml file to resolve a NameID attribute, encoded to the Identifier Format that you specified at the SP (Canvas). In the following

example, we generate an attribute named "principal" where the value is a duplicate of the "sAMAccountName" attribute which is determined by the Attribute Resolver with the id "myLDAP." The format is declared to match that specific in the Canvas configuration settings and is an attribute of type NameID.

 

<!-- NameID for Instructure Canvas SP -->

<resolver:AttributeDefinition id="principal" xsi:type="Simple"
 xmlns="urn:mace:shibboleth:2.0:resolver:ad" sourceAttributeID="sAMAccountName">

  <resolver:Dependency ref="myLDAP" />

  <resolver:AttributeEncoder xsi:type="enc:SAML2StringNameID"
 nameFormat="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified" />

</resolver:AttributeDefinition>

 

Edit attribute-filter.xml

Edit your /etc/shibboleth-idp/attribute-filter.xml file to add a policy for the Canvas SP. In this example, we create a rule that applies to the requester with the entity ID of "http://yourschool.instructure.com/saml2" (replace with your school's information).

 

This policy releases the NameID attribute named "principal" (configured above in attribute-resolver.xml) to Canvas, but only for users whose myMemberOf does NOT contain GshibDenyAccess (This extra rule may not be needed for your IdP).

 

<!-- Instructure Canvas-specific rule -->
<AttributeFilterPolicy id="InstructureCanvasPolicy">
  <PolicyRequirementRule xsi:type="basic:AND">
    <basic:Rule xsi:type="basic:NOT">
      <basic:Rule xsi:type="basic:AttributeValueRegex" attributeID="myMemberOf" regex="^.*CN=GshibDenyAccess.*$"/>
    </basic:Rule>
    <basic:Rule xsi:type="basic:AttributeRequesterString" value="http://www.instructure.com/saml2"/>
  </PolicyRequirementRule>
  <AttributeRule attributeID="principal">
    <PermitValueRule xsi:type="basic:ANY" />
  </AttributeRule>
</AttributeFilterPolicy>

 

Edit Edit /opt/shibboleth-idp/metadata/idp-metadata.xml [optional]

Edit /opt/shibboleth-idp/metadata/idp-metadata.xml and make sure you're using ONLY the <NameIDFormat> entry that matches the Identifier Format specified at the Canvas SP. This likely affects both the <IDPSSODescriptor> and <AttributeAuthorityDescriptor> elements. To keep with our example Canvas configuration settings, we use:

 

<NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified</NameIDFormat>

 

Enable additional logging in Shibboleth [optional]

Adjust your log settings for debugging purposes, in the file /etc/shibboleth-idp/logging.xml. Remember to change this back after everything is working if you don't want all these items to be logged all the time.

 

<logger name="PROTOCOL_MESSAGE"> <level value="ALL" /></logger>
<logger name="edu.internet2.middleware.shibboleth.common.attribute"> <level value="ALL" /></logger>

 

You can view the logged events by tailing the log file:

tail -f /var/log/shibboleth-idp/idp-process.log

 

Configure Canvas to work with Shibboleth IdP(s)

To configure Shibboleth in Canvas, you may choose to include some or all of the following information as part of the configuration as shown in the table below.

 

Configure the fields on this screen as follows:
IdP Entity IDRequired. An entity ID is a globally unique name for a SAML entity, either an Identity Provider (IdP) or a Service Provider (SP).
In almost all cases, an entity ID is an absolute URL but it's important to note that an entity ID is a name, not a location. That is, an entity ID need not resolve to an actual web resource.
Log On URLExample: https://shib.myschool.edu/idp/profile/SAML2/Redirect/SSO
Log Out URLURL where Canvas will redirect users when they log out.
Note: This URL will require the user to close their browser to end their session, but will take them back to your Shibboleth server’s logout page where you can display a warning about this.
Change Password URLSince Canvas does not manage passwords in a SSO integration, it will direct users to this address to manage/maintain their password.
Certificate FingerprintThe certificate is the public X.509 certificate that is used by the IdP to sign identity assertions. This is a representation in hex of the SHA1 hash of the public certificate.  Since this is of the public certificate, it is not a secret value.
Example: E9:A4:57:F0:BB:84:24:75:DB:56:D6:65:14:FC:9B:39:60:55:38:86
Login AttributeShould match what you selected in the Claim Rule setup, in our case it was User-Principal-Name > Name ID.
Identifier formatUsually set to urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified
The identifier format informs both the IdP and SP of how to interpret the value desired for the NameID assertion (essentially the “username”).  Canvas includes this in the initial request to the IdP.  Canvas does not interpret this value according to the associated semantic meaning of the attribute. Regardless of which format/attribute is chosen, Canvas will try to find a matching user-login.
Authentication Context99% of the time this is set to No Value.
Login LabelEnter a label for usernames.  This is used in a few places inside Canvas to refer to the username. This might be student number, an ID, username, or any number of other names. If you enter no value then Canvas will use Login ID.
Unknown User Url:Enter a URL that a user will be redirected to if their account is not found. If no value is entered, Canvas will simply display a page indicating that there was a problem logging in.
Position1

 

Configure Shibboleth in Canvas Authentication

Learn how to configure authentication in Canvas.

 

Debugging Authentication

SAML Messages End-to-End

Try logging on to Canvas using a different browser.

 

 

We'll follow all the SAML exchanges for a successful login.

 

SAML Message from SP to IdP

This messages kicks off the SSO. Canvas sends this authentication request using an HTTP Redirect. Canvas advertises it's identity, http://yourschool.instructure.com/saml2, and the URL of the Service (/saml_consume) where it will accept assertions using the HTTP POST bindings. It also requests the NameID attribute in the format specified in the configuration settings.

 

<?xml version="1.0" encoding="UTF-8"?><samlp:AuthnRequest xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol" AssertionConsumerServiceURL="https://mytest.instructure.com/saml_consume" ID="3473bb1eb5a7ee527e31ffe1e286ad4121b356f7e5" IssueInstant="2011-06-17T20:45:47Z" ProtocolBinding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Version="2.0"> <saml:Issuer xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion">http://www.instructure.com/saml2</saml:Issuer> <samlp:NameIDPolicy AllowCreate="true" Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified" xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"/> <samlp:RequestedAuthnContext Comparison="exact" xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"> <saml:AuthnContextClassRef xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion">urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport</saml:AuthnContextClassRef> </samlp:RequestedAuthnContext> </samlp:AuthnRequest>

 

SAML message from IDP to SP

After the user successfully authenticates to the Shibboleth IdP, they are redirected back to Canvas using an HTTP POST where the payload is the following assertion. The assertion includes the signature, which is verified to have originated from the associated X.509 certificate.

 

Canvas computes the fingerprint of the supplied X.509 certificate and compares that with the fingerprint from the configuration settings.

 

<?xml version="1.0" encoding="UTF-8"?><saml2p:Response xmlns:saml2p="urn:oasis:names:tc:SAML:2.0:protocol"Destination="https://mytest.instructure.com/saml_consume" ID="_db75f64afd82d2f65c53982b93e94fa5"InResponseTo="3473bb1eb5a7ee527e31ffe1e286ad4121b356f7e5" IssueInstant="2011-06-17T20:46:03.621Z" Version="2.0"> <saml2:Issuer xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion" Format="urn:oasis:names:tc:SAML:2.0:nameid-format:entity">urn:mace:incommon:myschool.edu</saml2:Issuer> <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#"> <ds:SignedInfo> <ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/> <ds:SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/> <ds:Reference URI="#_db75f64afd82d2f65c53982b93e94fa5"> <ds:Transforms> <ds:Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/> <ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/> </ds:Transforms> <ds:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/> <ds:DigestValue>GuPWrQwOVUMYVk2ETm4pYr+im0Q=</ds:DigestValue> </ds:Reference> </ds:SignedInfo> <ds:SignatureValue>A36yXZpeZBSAk5NA2j/wLeYhuX4vY1cdec...sEJqf6t6cGnf9TkSCdW5Csgb8uC9pPSg==</ds:SignatureValue> <ds:KeyInfo> <ds:X509Data> <ds:X509Certificate>MIIDPjCCAiagAwIBAgIJANtc2NbmMudXMwHhcNMTEwNDA3MTQxMD...LdBjEL0HPh0mr1ynZK4DSpncep</ds:X509Certificate> </ds:X509Data> </ds:KeyInfo> </ds:Signature> <saml2p:Status> <saml2p:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success"/> </saml2p:Status> <saml2:Assertion xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion" ID="_aebdca06c494a406fda185373279d9dd" IssueInstant="2011-06-17T20:46:03.621Z" Version="2.0"> <saml2:Issuer Format="urn:oasis:names:tc:SAML:2.0:nameid-format:entity">urn:mace:incommon:myschool.edu</saml2:Issuer> <saml2:Subject> <saml2:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified" //--- here above you see the configured format coming back NameQualifier="urn:mace:incommon:myschool.edu" SPNameQualifier="http://www.instructure.com/saml2"> shibtest  //------ this is the value that Canvas will use to look up a user-login </saml2:NameID> <saml2:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer"> <saml2:SubjectConfirmationData Address="192.168.1.1" InResponseTo="3473bb1eb5a7ee527e31ffe1e286ad4121b356f7e5" NotOnOrAfter="2011-06-17T20:51:03.621Z" Recipient="https://mytest.instructure.com/saml_consume"/> </saml2:SubjectConfirmation> </saml2:Subject> <saml2:Conditions NotBefore="2011-06-17T20:46:03.621Z" NotOnOrAfter="2011-06-17T20:51:03.621Z"> <saml2:AudienceRestriction> <saml2:Audience>http://www.instructure.com/saml2</saml2:Audience> </saml2:AudienceRestriction> </saml2:Conditions> <saml2:AuthnStatement AuthnInstant="2011-06-17T20:46:03.373Z" SessionIndex="903204ff20d9dfa711c654cd2af60d85fd2a13e3706846798ee38c8f302b4fdd"> <saml2:SubjectLocality Address="192.168.1.1"/> <saml2:AuthnContext> <saml2:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport</saml2:AuthnContextClassRef> </saml2:AuthnContext> </saml2:AuthnStatement> </saml2:Assertion></saml2p:Response>

 

After the user successfully authenticates to the Shibboleth IdP, they are redirected back to Canvas using an HTTP POST where the payload is the following assertion. The assertion includes the signature, which is verified to have originated from the associated X.509 certificate.

 

Canvas computes the fingerprint of the supplied X.509 certificate and compares that with the fingerprint from the configuration settings.

 

<?xml version="1.0" encoding="UTF-8"?><saml2p:Response xmlns:saml2p="urn:oasis:names:tc:SAML:2.0:protocol" Destination="https://mytest.instructure.com/saml_consume" ID="_db75f64afd82d2f65c53982b93e94fa5" InResponseTo="3473bb1eb5a7ee527e31ffe1e286ad4121b356f7e5" IssueInstant="2011-06-17T20:46:03.621Z" Version="2.0"> <saml2:Issuer xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion"
Format="urn:oasis:names:tc:SAML:2.0:nameid-format:entity">urn:mace:incommon:myschool.edu</saml2:Issuer> <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#"> <ds:SignedInfo> <ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/> <ds:SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/> <ds:Reference URI="#_db75f64afd82d2f65c53982b93e94fa5"> <ds:Transforms> <ds:Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/> <ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/> </ds:Transforms> <ds:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/> <ds:DigestValue>GuPWrQwOVUMYVk2ETm4pYr+im0Q=</ds:DigestValue> </ds:Reference> </ds:SignedInfo> <ds:SignatureValue>A36yXZpeZBSAk5NA2j/wLeYhuX4vY1cdec sEJqf6t6cGnf9TkSCdW5Csgb8uC9pPSg==</ds:SignatureValue> <ds:KeyInfo> <ds:X509Data> <ds:X509Certificate> MIIDPjCCAiagAwIBAgIJANtc2N bmMudXMwHhcNMTEwNDA3MTQxMD LdBjEL0HPh0mr1ynZK4DSpncep</ds:X509Certificate> </ds:X509Data> </ds:KeyInfo> </ds:Signature> <saml2p:Status> <saml2p:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success"/> </saml2p:Status> <saml2:Assertion xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion" ID="_aebdca06c494a406fda185373279d9dd" IssueInstant="2011-06-17T20:46:03.621Z" Version="2.0"> <saml2:Issuer Format="urn:oasis:names:tc:SAML:2.0:nameid-format:entity">urn:mace:incommon:myschool.edu</saml2:Issuer> <saml2:Subject> <saml2:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified" //--- here above you see the configured format coming back NameQualifier="urn:mace:incommon:myschool.edu" SPNameQualifier="http://www.instructure.com/saml2"> shibtest  //------ this is the value that Canvas will use to look up a user-login </saml2:NameID> <saml2:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer"> <saml2:SubjectConfirmationData Address="192.168.1.1" InResponseTo="3473bb1eb5a7ee527e31ffe1e286ad4121b356f7e5" NotOnOrAfter="2011-06-17T20:51:03.621Z" Recipient="https://mytest.instructure.com/saml_consume"/> </saml2:SubjectConfirmation> </saml2:Subject> <saml2:Conditions NotBefore="2011-06-17T20:46:03.621Z" NotOnOrAfter="2011-06-17T20:51:03.621Z"> <saml2:AudienceRestriction> <saml2:Audience>http://www.instructure.com/saml2</saml2:Audience> </saml2:AudienceRestriction> </saml2:Conditions> <saml2:AuthnStatement AuthnInstant="2011-06-17T20:46:03.373Z" SessionIndex="903204ff20d9dfa711c654cd2af60d85fd2a13e3706846798ee38c8f302b4fdd"> <saml2:SubjectLocality Address="192.168.1.1"/> <saml2:AuthnContext>
<saml2:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport</saml2:AuthnContextClassRef> </saml2:AuthnContext> </saml2:AuthnStatement> </saml2:Assertion></saml2p:Response>The requested NameID format was successfully sent back to the Canvas SP, as the followingsub-snippet from above. Note it has "shibtest" as its value:<saml2:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified" NameQualifier="urn:mace:incommon:myschool.edu" SPNameQualifier="http://www.instructure.com/saml2">shibtest</saml2:NameID>

 

Troubleshooting

 

SymptomPossible CauseRemedy
User can't loginUser doesn't exist in CanvasorUser's login_id in Canvas doesn't match incoming Shibboleth response.Create userorUpdate login id in Canvas or change Shibboleth responseorCheck debugging output to be sure authentication is succeeding and expected  information is being sent from the Idp for their Canvas login_id.
Canvas reports "unknown user: username"User doesn't exist in CanvasorUser's login_id in Canvas doesn't match incoming Shibboleth response.Create userorUpdate login id in Canvas or change Shibboleth response

 

Additional Reading

Shibboleth Documentation: https://wiki.shibboleth.net/confluence/display/SHIB2/Home

1 person found this helpful

Attachments

    Outcomes