Instructure Canvas Integration Guide

This is not a replacement for the actual documentation and you cannot cut and paste your way to a working system. The examples are not usable without taking into consideration your local needs and requirements.

Canvas by Instructure is a learning environment used by a number of institutions.

Identity Provider Metadata

The Service Providers platform consumes metadata from the UK federation and InCommon, they advise that the metadata consumption is handled by their backend, therefore if your IdP appears there you can enter the Metadata URI as either urn:mace:incommon or http://ukfederation.org.uk

These are not the Metadata URIs for these federations, the SPs terminology is wrong, they are matching to another element in the metadata aggregates.
It is unclear which metadata publication they are consuming, or whether they are following federation technical recommendations such as signature verification or regular updating is unclear.

The following options for the can be configured in the SPs self-service portal;

IdP Metadata URI
IdP EntityID
Log on URL (no need to enter this if using federation)
Log out URL (no need to enter this if using federation)
Certificate Fingerprint (this is your Signing certificate fingerprint)
Login attribute (this only has the option of NameID)
Strip Domain From Login Attribute Value
Identifier Format (they have the full list of NameID formats here, in this example we use urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified)
Authentication context (they have a list here, in this example we use urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport)
Message signing, leave at RSA-SHA256

Service Provider Metadata

The Service Provider provides metadata at the entityID for the SP https://customer.instructure.com/saml2, this appears to be updated automatically with RequestedAttributes per the configuration in the self-service portal.

You can request that the SP register their metadata in the respective federation, they have entities registered in the UK federation and InCommon for their customers instances (see REFEDS Metadata Explorer for examples already registered)

Profile Requirements

Supports signed responses, which is the Shibboleth default.
Encryption is supported using AES128-CBC
Will for most configurations require a NameID override

Example Shibboleth Configuration

Refer to the RelyingPartyConfiguration topic and be cognizant that creating overrides for every service is generally an inefficient use of the software. Consider identifying common requirements across services and create overrides tied to multiple services that share those requirements, or that reference profile configuration beans containing common settings.

Example relying-party.xml override

	<!-- Container for any overrides you want to add. -->

	<util:list id="shibboleth.RelyingPartyOverrides">

		<!-- other overrides... -->

		<!-- SPs that required signed assertions but don't indicate that in their metadata. -->
		<bean parent="RelyingPartyByName" c:relyingPartyIds="http://customer.instructure.com/saml2">
            <property name="profileConfigurations">
                <list>
                   <bean parent="SAML2.SSO" p:nameIDFormatPrecedence="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified" />
                   <ref bean="SAML2.Logout" />
                </list>
            </property>
        </bean>


	</util:list>

Account Provisioning

The SP supports both manual and just-in-time provisioning, you'll need to map an attribute to their SIS ID and other attributes such as mail.

Authentication requests are initiated from https://customer.instructure.com/login/saml

NameID Requirements

The attribute sent in the NameID in the SAML Subject is matched to the Name in the application, therefore cn or CommonName was used in this instance, using a NameFormat of urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified, this can be configured in the self service portal of the SP, it will appear in the NameIDPolicy as part of the AuthnRequest, so will need to be consistent with your IdPs configuration for this RelyingParty.

Example Shibboleth Configuration

Refer to the NameIDGenerationConfiguration topic for a full treatment of NameID features.

Example saml-nameid.xml changes

	<!-- SAML 2 NameID Generation -->
	<util:list id="shibboleth.SAML2NameIDGenerators">

		<ref bean="shibboleth.SAML2TransientGenerator" />

		<!--
		<ref bean="shibboleth.SAML2PersistentGenerator" />
		-->

		<!--
		Add custom support for unspecified NameID, assumes you've released
		the source attribute (cn) to any SPs expecting to get it.
		-->
        <bean parent="shibboleth.SAML2AttributeSourcedGenerator"
            p:omitQualifiers="true"
            p:format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified"
            p:attributeSourceIds="#{ {'cn'} }">
            <property name="activationCondition">
              <bean parent="shibboleth.Conditions.RelyingPartyId" c:candidates="#{{'http://customer.instructure.com/saml2'}}" />
            </property>
        </bean>


	</util:list>

Example attribute-filter.xml changes

  <AttributeFilterPolicy id="canvas-instructure">
    <PolicyRequirementRule xsi:type="Requester" value="http://customer.instructure.com/saml2"/>
    <AttributeRule attributeID="cn" permitAny="true"/>
  </AttributeFilterPolicy>

Attribute Requirements

SAML attributes are supported and can be mapped to their Name as an OID easily, they also appear in the RequestedAttributes in the SP generated metadata. You will need to map a SAML attribute to the SIS ID attribute in the service, this appears to be a key field used in manual provisioning, it appears to treat these values case sensitively in SAML, but not with other plugins authentication sources such as LDAP (directly into Canvas), that can cause some issues during a migration.