Authentication Providers

An AuthenticationProvider object looks like:

{
  // Valid for SAML providers.
  "identifier_format": "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress",
  // Valid for all providers.
  "auth_type": "saml",
  // Valid for all providers.
  "id": 1649,
  // Valid for SAML providers.
  "log_out_url": "http://example.com/saml1/slo",
  // Valid for SAML and CAS providers.
  "log_in_url": "http://example.com/saml1/sli",
  // Valid for SAML providers.
  "certificate_fingerprint": "111222",
  // Valid for SAML providers.
  "requested_authn_context": null,
  // Valid for LDAP providers.
  "auth_host": "127.0.0.1",
  // Valid for LDAP providers.
  "auth_filter": "filter1",
  // Valid for LDAP providers.
  "auth_over_tls": null,
  // Valid for LDAP and CAS providers.
  "auth_base": null,
  // Valid for LDAP providers.
  "auth_username": "username1",
  // Valid for LDAP providers.
  "auth_port": null,
  // Valid for all providers.
  "position": 1,
  // Valid for SAML providers.
  "idp_entity_id": "http://example.com/saml1",
  // Valid for SAML providers.
  "login_attribute": "nameid",
  // Valid for SAML providers.
  "sig_alg": "http://www.w3.org/2001/04/xmldsig-more#rsa-sha256",
  // Just In Time provisioning. Valid for all providers except Canvas (which has
  // the similar in concept self_registration setting).
  "jit_provisioning": null,
  "federated_attributes": null,
  // If multi-factor authentication is required when logging in with this
  // authentication provider. The account must not have MFA disabled.
  "mfa_required": null
}

A SSOSettings object looks like:

// Settings that are applicable across an account's authentication
// configuration, even if there are multiple individual providers
{
  // The label used for unique login identifiers.
  "login_handle_name": "Username",
  // The url to redirect users to for password resets. Leave blank for default
  // Canvas behavior
  "change_password_url": "https://example.com/reset_password",
  // If a discovery url is set, canvas will forward all users to that URL when
  // they need to be authenticated. That page will need to then help the user
  // figure out where they need to go to log in. If no discovery url is
  // configured, the first configuration will be used to attempt to authenticate
  // the user.
  "auth_discovery_url": "https://example.com/which_account",
  // If an unknown user url is set, Canvas will forward to that url when a service
  // authenticates a user, but that user does not exist in Canvas. The default
  // behavior is to present an error.
  "unknown_user_url": "https://example.com/register_for_canvas"
}

A FederatedAttributesConfig object looks like:

// A mapping of Canvas attribute names to attribute names that a provider may
// send, in order to update the value of these attributes when a user logs in.
// The values can be a FederatedAttributeConfig, or a raw string corresponding
// to the "attribute" property of a FederatedAttributeConfig. In responses, full
// FederatedAttributeConfig objects are returned if JIT provisioning is enabled,
// otherwise just the attribute names are returned.
{
  // A comma separated list of role names to grant to the user. Note that these
  // only apply at the root account level, and not sub-accounts. If the attribute
  // is not marked for provisioning only, the user will also be removed from any
  // other roles they currently hold that are not still specified by the IdP.
  "admin_roles": null,
  // The full display name of the user
  "display_name": null,
  // The user's e-mail address
  "email": null,
  // The first, or given, name of the user
  "given_name": null,
  // The secondary unique identifier for SIS purposes
  "integration_id": null,
  // The user's preferred locale/language
  "locale": null,
  // The full name of the user
  "name": null,
  // The unique SIS identifier
  "sis_user_id": null,
  // The full name of the user for sorting purposes
  "sortable_name": null,
  // The surname, or last name, of the user
  "surname": null,
  // The user's preferred time zone
  "timezone": null
}

A FederatedAttributeConfig object looks like:

// A single attribute name to be federated when a user logs in
{
  // The name of the attribute as it will be sent from the authentication provider
  "attribute": "mail",
  // If the attribute should be applied only when provisioning a new user, rather
  // than all logins
  "provisioning_only": false,
  // (only for email) If the email address is trusted and should be automatically
  // confirmed
  "autoconfirm": false
}

List authentication providers

AuthenticationProvidersController#index

GET /api/v1/accounts/:account_id/authentication_providers

Scope: url:GET|/api/v1/accounts/:account_id/authentication_providers

Returns a paginated list of authentication providers

Example Request:

curl 'https://<canvas>/api/v1/accounts/<account_id>/authentication_providers' \
     -H 'Authorization: Bearer <token>'

Returns a list of AuthenticationProvider objects.

Update authentication provider

AuthenticationProvidersController#update

PUT /api/v1/accounts/:account_id/authentication_providers/:id

Scope: url:PUT|/api/v1/accounts/:account_id/authentication_providers/:id

Update an authentication provider using the same options as the create endpoint. You can not update an existing provider to a new authentication type.

Example Request:

# update SAML config
curl -XPUT 'https://<canvas>/api/v1/accounts/<account_id>/authentication_providers/<id>' \
     -F 'idp_entity_id=<new_idp_entity_id>' \
     -F 'log_in_url=<new_url>' \
     -H 'Authorization: Bearer <token>'

Returns an AuthenticationProvider object.

Get authentication provider

AuthenticationProvidersController#show

GET /api/v1/accounts/:account_id/authentication_providers/:id

Scope: url:GET|/api/v1/accounts/:account_id/authentication_providers/:id

Get the specified authentication provider

Example Request:

curl 'https://<canvas>/api/v1/accounts/<account_id>/authentication_providers/<id>' \
     -H 'Authorization: Bearer <token>'

Returns an AuthenticationProvider object.

Delete authentication provider

AuthenticationProvidersController#destroy

DELETE /api/v1/accounts/:account_id/authentication_providers/:id

Scope: url:DELETE|/api/v1/accounts/:account_id/authentication_providers/:id

Delete the config

Example Request:

curl -XDELETE 'https://<canvas>/api/v1/accounts/<account_id>/authentication_providers/<id>' \
     -H 'Authorization: Bearer <token>'

show account auth settings

AuthenticationProvidersController#show_sso_settings

GET /api/v1/accounts/:account_id/sso_settings

Scope: url:GET|/api/v1/accounts/:account_id/sso_settings

The way to get the current state of each account level setting that’s relevant to Single Sign On configuration

You can list the current state of each setting with “update_sso_settings”

Example Request:

curl -XGET 'https://<canvas>/api/v1/accounts/<account_id>/sso_settings' \
     -H 'Authorization: Bearer <token>'

Returns a SSOSettings object.

update account auth settings

AuthenticationProvidersController#update_sso_settings

PUT /api/v1/accounts/:account_id/sso_settings

Scope: url:PUT|/api/v1/accounts/:account_id/sso_settings

For various cases of mixed SSO configurations, you may need to set some configuration at the account level to handle the particulars of your setup.

This endpoint accepts a PUT request to set several possible account settings. All setting are optional on each request, any that are not provided at all are simply retained as is. Any that provide the key but a null-ish value (blank string, null, undefined) will be UN-set.

You can list the current state of each setting with “show_sso_settings”

Example Request:

curl -XPUT 'https://<canvas>/api/v1/accounts/<account_id>/sso_settings' \
     -F 'sso_settings[auth_discovery_url]=<new_url>' \
     -F 'sso_settings[change_password_url]=<new_url>' \
     -F 'sso_settings[login_handle_name]=<new_handle>' \
     -H 'Authorization: Bearer <token>'

Returns a SSOSettings object.

---

This documentation is generated directly from the Canvas LMS source code, available on Github.