Table of Contents
Overview
Requirements
How It Works
How to Do It
Available Attributes
Configuring & Enabling the Feature
Logging in for the First Time
Related Articles
Overview
Coursedog supports the creation of users as well as the assignment of roles and departments via Single-Sign On (SSO).
Requirements
This feature only pertains to SAML-based authentication.
Your institution must configure and send users roles and departments in the SAML attributes payload. These are typically sent in the form of “isMemberOf” attributes. It is up to you how these are defined in your system.
You need to configure single sign-on with Coursedog before you can create users and assign roles via SSO.
Roles and departments must exist in Coursedog before you can configure this feature.
You must configure this feature in Admin > Settings > Auth Settings > Saml > SSO User Provisioning Attributes.
How It Works
User accounts are both created and updated based on the presence of two distinct attributes in the SAML isMemberOf payload: Schools and Departments and Roles.
This payload can have multiple entries for roles and departments.
The isMemberOf attribute can have multiple nested attributes.
Each of these works in tandem to both create users in the Coursedog instance/school and assign the appropriate roles and departments in the user profile.
The user must log into Coursedog (authenticate) to be created, updated, and/or assigned roles/departments.
How to Do It
Create SAML isMemberOf attributes in your IDM system and/or SIS (see examples below).
Assign users to attributes in your IDM system.
Configure and enable SSO User Provisioning Attributes in Coursedog.
Available Attributes
Schools and Departments | Roles | First Name | Last Name
Email or Institution ID Attribute | Multiple School Attributes
Schools and Departments
Overview
The schools and departments attribute determines the:
Coursedog instance/school where the user is created.
Coursedog instance/school where the role is assigned.
Primary Academic Department and Secondary Departments assigned to the user.
Example Attribute
In the below example, the user is created in demoschool_jeff and the chemistry department is assigned as the “Primary Academic Department”.
If more than one department is sent in the payload, the first department is assigned as the Primary Academic Department and the remaining departments are assigned as Secondary Departments.
cn=app:coursedog:policy:organizations:demoschool_jeff:chemistry
Roles
Overview
The roles attribute assigns a role to the user's profile.
Please note all Coursedog roles should have a corresponding attribute in your school’s user directory; otherwise, the role will be wiped during provisioning. See Step 4 below under “Configuring & Enabling the Feature”.
Each time a user logs into Coursedog, we update all the properties that are defined in our admin panel and delivered with the SAML payload unless you use the “Do not update user attributes” setting (see below). We're flexible in mapping, so you can maintain your roles (regardless of names) in your system, and the names will translate to our roles according to the mapping you defined.
Example Attribute
In the below example, the user is assigned the Coursedog role in their user profile.
For system schools, the role is assigned to all schools sent in the Schools and Departments attributes.
Read more about Default Roles below.
cn=app:coursedog:policy:roles:coursedog
First Name
Overview
The first name attribute assigns a first name to the user's profile.
Example Attribute
In the below example, the user is assigned the first name of “Jeff” in their user profile.
cn=Jeff
Last Name
Overview
The last name attribute assigns a last name to the user's profile.
Example Attribute
In the below example, the user is assigned the last name of “Demo” in their user profile.
cn=Demo
Email or Institution ID Attribute
Overview
This optional field only needs to be used if InstitutionId is used to map to the user in your global SSO configuration. In which case, you will see “Email attribute” here.
Use “Email attribute” to create users with the designated email (see example below).
If Email is used to map to the user, you will see “Institution ID attribute” here. You can leave the field blank, but it can also be used in the event that your institution changes its matching strategy.
Example Email Attribute
urn:oid:1.2.2.4
Multiple School Attributes
Overview
System schools (i.e. more than one Coursedog instance) might wish to send two or more attributes to provision access for each respective school.
Example Attribute
In the below example, the same user would be created in both demoschool_jeff and demoschool_justin and would be assigned to two departments in demoschool_justin (we can send multiple departments for the same school).
cn=app:coursedog:policy:organizations:demoschool_jeff:chemistry
cn=app:coursedog:policy:organizations:demoschool_justin:biology
cn=app:coursedog:policy:organizations:demoschool_justin:arts
Configuring & Enabling the Feature
Overview | How to Do It | Mapping Examples | Wildcards
Overview
Once attributes are created in the IDM system/SIS, the attribute ids and “structure” must be configured and then enabled.
How to Do It
Step 1: Navigate to Admin > Settings > Auth Settings > Saml > SSO User Provisioning Attributes.
Step 2: Configure Attribute IDs and structures for: isMemberOf, First Name, Last Name, Department Structure and Role Structure.
isMemberOf
This is the SAML attribute id that will be read for member groups during authentication.
Department Structure (Schools and Departments)
The attribute string that will be consumed for schools and departments assignments.
In the event you don’t wish to enforce case sensitivity for departments attributes, you can disable this by selecting “No” under “Departments case sensitive”.
Role Structure (Roles)
The attribute string that will be consumed for role assignments.
firstNameAttribute
The attribute string that will define the first name of the user.
lastNameAttribute
The attribute string that will define the last name of the user.
Step 3: Populate “Default roles” and “Default products”.
Default Roles
Whatever you input here for the Default Role will be assigned if no role is sent in the attributes.
If no attribute is sent and Default Role is not configured, no role will be assigned. the role will be assigned as empty/blank.
Default Products
Default Products must be configured here.
Whatever you input here is what will be assigned to all users who are provisioned using this method.
Multiple products can be assigned.
Products cannot currently be assigned via SAML attributes.
Step 4:
You can create mappings for Schools and Roles between the IDM/SIS and Coursedog using the “Roles (Add)” and “Schools (Add)” settings in the modal.
For example, if the “super_admin” role is sent in the SAML attributes, this can be mapped to the “superAdmin” role in Coursedog.
Coursedog will read these mappings and assign the appropriate values.
Mappings must be configured in Admin > Settings > Auth Settings > SSO User Provisioning Attributes > Mappings
A list of all existing Coursedog roles and schools is presented in the Value dropdown for each, respectively. It’s important you create Roles in Coursedog before enabling this feature.
See “Mappings” below to learn more.
Step 5 (Optional):
For most schools, the “Do not update user attributes” box should stay unchecked.
If the option is unchecked – the recommended setting for most schools – user attributes will be managed in the IDP and automatically updated in Coursedog every time the user logs in.
Only check the “Do not update user attributes” box if you’d like to automatically create users and assign attributes upon their first login, but then after that first login will manually manage department and role assignments in Coursedog rather than your IDP.
If this option is checked, a user will be created upon their first login but none of their attributes will be updated on subsequent logins.
Step 6:
Once everything else has been configured on this modal, enable SSO User Provisioning Attributes by selecting “Yes” under “Enabled”.
Do not enable until all configurations are in place.
Step 7: Click “Save” to retain your work and close out of the modal.
Mapping Examples
Overview | Example Role Structure | Example School and Department Structure
Overview
As indicated above under Step 5, you can create mappings for Schools and Roles between the IDM/SIS and Coursedog.
At least one School mapping is required for user provisioning to work properly.
Two examples are captured below, but note that “Role Structure” and “School and Department Structure” are actually determined by your settings.
Your institution defines the structures and shows us what the structure looks like.
For the role structure, for example, we’re showing one example below that isn’t necessarily how yours will look. However, we do recommend:
Prefixing the roles you send us so we receive, for example, roles:<roles> structure.
Renaming the roles you send to Coursedog to match the ASCII word characters ([a-zA-Z0-9_]).
Coursedog will ingest whatever structure you provide and then take the <role> wildcard as the actual role the user belongs to.
Example Role Structure
cn=app:coursedog:policy:roles:<role>
What You Send
cn=app:coursedog:policy:roles:super_admin
Resulting Configuration
Example School and Department Structure
cn=app:coursedog:policy:organizations:<school>:<department>
What You Send
cn=app:coursedog:policy:organizations:demoschool:chemistry
Resulting Configuration
Special Note for Departments
Departments cannot currently be mapped to Coursedog.
The departments attributes assigned to users attributes must be identical to the department codes in Coursedog.
For example, if the department code in Coursedog is CHEM, the attribute must also contain CHEM.
Wildcards
Overview
You can have wildcards or variable details in the schools and roles attributes string.
This is particularly helpful in tools such as Grouper, which use inheritance to assign the appropriate departments based on a parent/child structure.
For example, you assign a user to the “college_of_arts” group, therefore they inherit all departments in this group (history and biology). We can account for this using wildcards.
Example
What You Send
cn=app:coursedog:policy:organizations:demoschool_jeff:college_of_arts:history
cn=app:coursedog:policy:organizations:demoschool_jeff:college_of_science:biology
Resulting Configuration
Handled with the wild card expression <any> in the Department Structure.
Logging in for the First Time
When new users are created using the above method, the first time they log in they will need to do so via the following URLs:
https://app.coursedog.com/#/login/INSTITUTION ID (Production)
https://staging.coursedog.com/#/login/INSTITUTION ID (Staging)
Make sure you replace “INSTITUTIONID” in the URL with your institution’s ID.
If you’re unsure what that is, you can find it at Admin > Settings > School Unique ID.
After that initial log-in, users can log in via https://staging.coursedog.com/ (staging) or https://app.coursedog.com (production), depending on which environment they need to access.