Authentication Providers API
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>'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>'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 -X PUT '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>'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 -X DELETE 'https://<canvas>/api/v1/accounts/<account_id>/authentication_providers/<id>' \
-H 'Authorization: Bearer <token>'Restore a deleted authentication provider AuthenticationProvidersController#restore
PUT /api/v1/accounts/:account_id/authentication_providers/:id/restore
Scope:
url:PUT|/api/v1/accounts/:account_id/authentication_providers/:id/restore
Restore an authentication provider back to active that was previously deleted. Only available to admins who can manage_account_settings for given root account.
Example Request:
curl -X PUT 'https://<canvas>/api/v1/accounts/<account_id>/authentication_providers/<id>/restore' \
-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>'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>'