|
Official Canvas Document |
 |
- Background
- Authentication Terminology
- Prerequisites
- Test and Beta Canvas Sites
- Login Release Valve
- Configuring Shibboleth with Canvas
- Configure Shibboleth with Canvas Metadata
- Calculate Certificate Fingerprint on the IdP
- Obtain Canvas Metadata
- Adjust IdP Configuration Files
- Edit relying-party.xml to add Canvas SP metadata
- Edit attribute-resolver.xml to resolve a NameID
- Edit attribute-filter.xml
- Edit /opt/shibboleth-idp/metadata/idp-metadata.xml [optional]
- Enable additional logging in Shibboleth [optional]
- Configure Canvas to work with Shibboleth IdP(s)
- Configure Shibboleth in Canvas Authentication
- Debugging Authentication
- SAML Message from SP to IdP
- SAML message from IDP to SP
- Troubleshooting
- Additional Reading
Background
Single Sign On (SSO) is a functionality that many schools will configure during their Canvas implementation. SSO provides many benefits, not 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.
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 its 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.
Authentication Terminology
| Term | Definition |
| SAML | Security Assertion Markup Language |
| IdP | Identity 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. |
| SP | Service 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. |
| Metadata | Information 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). |
| SSO | Single 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. |
| SLO | Single 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_id | Username 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 ID | Unique ID of a user in Canvas. Used to link a user to an outside system, often a Student Information System (SIS). |
| SIS | Student Information System |
Prerequisites
- Any user that needs to authenticate via Shibboleth must already have a user account provisioned in Canvas. User accounts must either be created manually in the web interface, through the SIS import CSVs, an SIS integration, or Just In Time Provisioning.
- The login_id field in Canvas must match the username field returned from Shibboleth.
Test and Beta Canvas Sites
Your Canvas instance may include multiple environments, such as beta or test.
The Canvas metadata contains AssertionConsumerService URLs for each of the Canvas environments. With a single entity ID, there may be some confusion around how to configure the IdP to work for these seemingly separate environments. You should consider all environments 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.
Login Release Valve
It is possible you may lock yourself out of Canvas while you are working to setup authentication. If this happens, there is a way to log in to Canvas using local authentication. Simply go to http:// <yourcanvasname>.instructure.com/login/canvas (This forces Canvas to display the local login form rather than redirecting to the SAML login page).
Configuring Shibboleth with Canvas
Configuring Shibboleth and Canvas to work together involves the following steps:
- Configure Shibboleth with Canvas Metadata
- 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
Change as needed for your own configuration.
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" |
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 /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 ID | Required. 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 URL | Example: https://shib.myschool.edu/idp/profile/SAML2/Redirect/SSO |
| Log Out URL | URL 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 URL | Since Canvas does not manage passwords in a SSO integration, it will direct users to this address to manage/maintain their password. |
| Certificate Fingerprint | The 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 Attribute | Should match what you selected in the Claim Rule setup, in our case it was User-Principal-Name > Name ID. |
| Identifier format | Usually 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 Context | No Value (default) |
| Login Label | Enter a label for usernames. This is used in 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. |
| Position | 1 |
Configure Shibboleth in Canvas Authentication
Learn how to configure authentication in Canvas.
Debugging Authentication
SAML Message from SP to IdP
This messages kicks off the SSO. Canvas sends this authentication request using an HTTP Redirect. Canvas advertises its 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
| Symptom | Possible Cause | Remedy |
| User can't login | 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 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
