Why a Discovery Page, also what is a Discovery Page?

mcotterman
Community Novice
‎01-30-2018 08:44 AM
0
23998

In some cases an institution using Canvas may have users who authenticate to Canvas using more than one authentication mechanism each using a different page for the collection of authentication credentials (usernames and passwords usually).

For example an institution may have a SAML IdP configured for the bulk of their users (ex: students and teachers), but are using Canvas authentication for another type of users (ex: Parents of K-12 students or guest lecturers). Another example may be users from different institutions who login to the same Canvas instance using two different SAML IdPs.

When situations like this occur it is necessary for users to be given a special login URL to login to Canvas, so that Canvas can present or redirect the user to the appropriate login page. This can be confusing to users because if they go directly to a Canvas URL and they are not logged in to Canvas they will be presented with the login page for the first authentication provider in your Authentication settings configuration list which may not be the correct login page for that user.

The solution to this challenge is to add a "Discovery URL" to your Authentication settings page in Canvas. Once configured, users who are not already logged in to Canvas will be redirected to the URL in the "Discovery URL" field unless the Canvas web address they are attempting to visit is a specific login URL. This allows a Canvas admin to provide a location that displays links to the appropriate Canvas login URLs for various types of users.

PRO-TIP: The links to the specific Canvas login URLs are the only important component of this web page and they must be in a specific format (keep reading for more). As such, a best practice is to make the links very prominent on the page.

How do I know how to craft a Canvas Login URL?

I'm glad you asked!  There are two ways the URLs may need to be formatted.

  1. If you have only one authentication provider of a specific type (SAML,LDAP, etc) then the URL will be in the following format:
    https://[canvas_URL]/login/[type]

    [canvas_URL] = Your Canvas address. Example: school.instructure.com

    [type] = The type of authentication. This information is available within the "Authentication Settings" page after you add the authentication provider in Canvas.
    Here are some examples of how this information appears in Canvas:

    Single SAML Configuration in Canvas (/login/SAML):

    SAML
    Canvas authentication example in Canvas (/login/canvas):

    Canvas
  2. If you have more than one of the same authentication type (ex: 2 different SAML IdP configurations):
    https://[canvas_URL]/login/[type]/[id]

    [canvas_URL] = Your Canvas address. Example: school.instructure.com

    [type] = The type of authentication. This information is available within the "Authentication Settings" page after you add the authentication provider in Canvas.

    [id] = The ID number for the specific authentication provider configuration.
    The URL described in the first scenario above would only work for the first authentication of that type in the list (example: multiple SAML IdPs). As a result the Authentication settings page will display a new, more specific, login URL after the second authentication provider of the same type has been added.

    An example when multiple SAML IdP configurations are in Canvas (/login/saml/#):

    SAML Example

Ok...So what do I do with these URLs?

Now that you have the special Canvas login URLs you are ready to build a web page. Sorry, I'm not going to tell you how to do that, but if you work with your web designer or specialist they should be able to help you build a simple web page that contains the links you need for a discovery page. You will also need some place to host the web page that is accessible to the entire Internet. Once you have this page built and have placed it on the web you should place the web address (URL) to that web page in the Discovery URL field of your Authentication settings page and save the settings.

Here is a brief summary of the steps:

  1. Create a web page that contains links to the Canvas URLs for the desired Canvas login URLs
  2. Put the web page in a publicly accessible web location (for read only of course)
  3. Enter the URL to the page in the Discovery URL field of your Authentication settings page in Canvas
  4. Save the settings
  5. Give it a try in an incognito or private window

I think I get it, but do you have an example?

Sure thing! There is an example of a very basic Discovery Page in our community source and unsupported GitHub repository. This example uses a Canvas URL of "canvas.instructure.com". So...if you want to use a copy of this page to use for your Discovery Page then you will need to change the links to point at your Canvas URL at a minimum.

Oh...I should also mention that the links on the example page are unlikely to work, so don't click them. It is just an example.

Example Page