Azure AD Authentication

When Forms Builder is installed on premises, authentication of users is handled by the Security Token Service (STS) component.

  • Users of sequences associated with the Student/Contact role are authenticated by the Student STS for Anthology Student or by the Contact STS for CampusNexus CRM.

  • Users of sequences associated with the Staff role are authenticated by the Staff STS.

The authentication token returned by the STS identifies the user's role. The token enables the user to log in to Portal and access authenticated sequences as Student/Contact or Staff.

Forms Builder 3.4 and later can also be deployed in a cloud (Azure) environment with Active Directory (AD) authentication. In this environment, the STS component is not used. In an Azure AD environment, the authentication process does not allow for role verification.

The logic to verify the user's role must be embedded in all form sequences that are deployed in an Azure AD environment. Each workflow must include a LookupUser activity with UserType=Student or UserType=Staff as appropriate. The LookupUser activity with a proper UserType value ensures that student users cannot access staff sequences and vice versa. See Workflow Examples below.

Prevent Student Users from Accessing Form Designer

When student and staff users share the same Azure AD group, you need to take the following steps to ensure that only staff members can access Form Designer.

  1. Log in to your Azure tenant directory as administrator.

  2. Select Home > Enterprise applications.

    Azure Enterprise applications

  3. Select All applications and click the link on Cmc.FBDesigner.

  4. In the Manage menu, select Properties.

  5. In the Enabled for users to sign-in property, select Yes.

  6. In the User assignment required property, select Yes.

    Cmc.FbDesigner Properties

  7. In the Users and groups menu, click Add Users.

  8. In the Add Assignment form, select Users and groups.

  9. In the Users and groups drop-down list, find the staff group to which you want to give permissions to access Form Designer and click Select.

    AAD Group

All Anthology Student staff members will be maintained within the selected group. When new staff members are added, they need to be added to that group.

Any member of the staff group can access Form Designer, can create and publish forms, but cannot modify workflows. Workflow Composer authentication and authorization are controlled separately. See Workflow Composer in Installation Manager help.

Users that are not in the staff group, for example students users created via the CreatePortalAccount workflow activity, will receive a messages similar to the examples below when they try to access the URL for Form Designer

Access denied  Access denied

Workflow Examples

When sequences for Staff and Student roles are deployed in an Azure AD environment, the workflows need to include logic as detailed below. These workflow segments need to be placed in the first form of a sequence.

For staff sequences we recommend creating a landing page that does not display any information intended for staff users only. The landing page should display a validation error if an unauthorized user (i.e., student) tries to access the staff sequence.

The following workflow segment checks if a user is permitted to access a staff sequence. It checks for a valid staffid.

AAD Staff

  1. The Entry section of the first form contains a LookupUser activity with the following properties:

    UserId staffid
    UserName formInstance.UserName
    UserType Cmc.Nexus.FormsBuilder.Entities.UserType.Staff
    ValidationMessages formInstance.ValidationMessages

  2. An If condition checks if staffid = 0.

    1. The Then branch contains a CreateValidationItem activity with the following properties:

      Message "This staff user was not found"
      Messages formInstance.ValidationMessages
      MessageType Error
      Result <blank>

    2. The Else branch contains a GetEntity<StaffEntity> activity with the following properties:

      EntityId staffid
      Result staffEntity

  3. In the Next transition, check for a validation error to prevent the user from proceeding if the user's role does not match the role associated with the sequence. In the Condition field, specify not formInstance.ValidationMessages.HasErrors.

    Check for Validation Error

The following workflow segment checks if a user is permitted to access a student sequence. It creates a new student record if needed. The workflow denies access for staff users and prevents creating student records for users who logged in as staff.

AAD Student

  1. The Entry section of the first form contains a LookupUser activity with the following properties:

    UserId staffId
    UserName formInstance.UserName
    UserType Cmc.Nexus.FormsBuilder.Entities.UserType.Staff
    ValidationMessages formInstance.ValidationMessages

  2. An If condition checks if staffid > 0.

    This condition checks if a staff user is accessing a student sequence. The workflow prevents the staff user from running student sequence and ensures that if a new student attempts to create an account, a student record would not be created for a staff user.

    1. The Then branch contains a CreateValidationItem activity with the following properties:

      Message "Staff User Does Not Have Access to Run Student Sequence"
      Messages formInstance.ValidationMessages
      MessageType Error
      Result <blank>

    2. The Else branch contains a sequence with LookupUser activity for UserType=Student, followed by a condition that checks for a studentId, retrieves an existing StudentEntity or creates a Student Entity, and assigns required properties to the StudentEntity.

      AAD Student Only Check

      The Else branch contains a LookupUser activity with the following properties:

      UserId studentId
      UserName formInstance.UserName
      UserType Cmc.Nexus.FormsBuilder.Entities.UserType.Student
      ValidationMessages formInstance.ValidationMessages

      An If condition checks if studentId<=0.

      1. The Then branch contains a CreateEntity<StudentEntity> activity with the following property:

        Result studentEntity

        The following Assign activities are placed below the CreateEntity activity:

        To Value
        studentEntity.FirstName formInstance.UserInfo.FirstName
        studentEntity.LastName formInstance.UserInfo.LastName
        studentEntity.EmailAddress formInstance.UserInfo.EmailAddress
        studentEntity.CampusId formInstance.UserInfo.CampusId

      2. The Else branch contains a Get<StudentEntity> activity with the following properties:

        EntityId studentId
        Result studentEntity

      The following additional properties may need to be assigned to the StudentEntity below the Then and Else branches with the CreateEntity<StudentEntity> and GetEntity<StudentEntity>.activities.

      StudentEntity Properties

      *Assign values as appropriate for your environment.

      To Value*
      studentEntity.SchoolStatusId 1
      studentEntity.LeadDate datetime.Now
      studentEntity.IsActive true
      studentEntity.LeadSourceId 680
      studentEntity.AssignedAdmissionsRepId 2

  3. In the Next transition, check for a validation error to prevent the user from proceeding if the user's role does not match the role associated with the sequence. In the Condition field, specify Not formInstance.ValidationMessages.HasErrors.

    Check for Validation Error

For details about pre-populating formInstance.UserInfo variables when sequences are deployed in a cloud environment with Azure AD, see Azure AD Claims.

Login and Account Creation via Portal

For authenticated form sequences, Portal is used for both login and account creation and then control returns to Renderer. A page is displayed providing the option to log in using an existing Azure AD account or, if the user does not yet have an account, to create a new account. If "Create Account" is selected, the user will be redirected to the Portal.

login window

In Portal, the user will follow the steps to create an Azure AD account. The following fields are displayed when creating a new account:

  • Campus
  • First Name
  • Last Name
  • Email address
  • Username
  • Password
  • Security questions - if configured (e.g., Place of Birth, etc.)

Upon completion of the "Create new account" page, a new Azure AD account and Portal account (WpUser) will be created, and the user will be redirected back to the Portal login page.

The Login Locale setting can be used to add a drop-down list for locales on the Azure AD login page. For more information, see Login Locales.

If the "Create Account" option is selected on the Azure AD login page, the user is directed to the "New Account Creation" page in Portal. The header bar in Portal has a "Choose language" drop-down that is not linked to the Login Locales setting.

Renderer Web.Config Changes

When Forms Builder is installed in an Azure AD environment, the <issuers> section in the Forms Renderer web.config file will contain an "accountCreation" attribute that holds the Portal account creation URL.

    <!-- STS or Azure AD redirect URLs -->
    <issuers>
      <!-- <url key="A mapping issuerKey" 
					  value="An STS or Azure AD Login URL" 
					  accountCreation="If Azure AD, the portal account creation URL, otherwise empty" /> -->
      <url key="Student STS" accountCreation="<Portal account creation URL>" value="https://<server>.<domain>:<port>" />
      <url key="CRM STS" accountCreation="" value="https://<server>.<domain>:<port>" />
    </issuers>

Additional Renderer web.config changes may be necessary if the workflows for your authenticated forms (e.g., RFIs) use formInstance.UserInfo variables. For more information, see Azure AD Claims.

When Forms Builder is installed on premises, authentication of users is handled by the Security Token Service (STS) component.

  • Users of sequences associated with the Student/Contact role are authenticated by the Student STS for Anthology Student or by the Contact STS for CampusNexus CRM.

  • Users of sequences associated with the Staff role are authenticated by the Staff STS.

The authentication token returned by the STS identifies the user's role. The token enables the user to log in to Portal and access authenticated sequences as Student/Contact or Staff.

Forms Builder 3.4 and later can also be deployed in a cloud (Azure) environment with Active Directory (AD) authentication. In this environment, the STS component is not used. In an Azure AD environment, the authentication process does not allow for role verification.

The logic to verify the user's role must be embedded in all form sequences that are deployed in an Azure AD environment. Each workflow must include a LookupUser activity with UserType=Student or UserType=Staff as appropriate. The LookupUser activity with a proper UserType value ensures that student users cannot access staff sequences and vice versa. See Workflow Examples below.

Note: When student and staff users share the same Azure AD instance, some users need to be granted access to specific applications in Azure while other users need to be denied access. For more details about these configurations, see the following links:

Workflow Examples

When sequences for Staff and Student roles are deployed in an Azure AD environment, the workflows need to include logic as detailed below. These workflow segments need to be placed in the first form of a sequence.

For staff sequences we recommend creating a landing page that does not display any information intended for staff users only. The landing page should display a validation error if an unauthorized user (i.e., student) tries to access the staff sequence.

The following workflow segment checks if a user is permitted to access a staff sequence. It checks for a valid staffid.

AAD Staff

  1. The Entry section of the first form contains a LookupUser activity with the following properties:

    UserId staffid
    UserName formInstance.UserName
    UserType Cmc.Nexus.FormsBuilder.Entities.UserType.Staff
    ValidationMessages formInstance.ValidationMessages

  2. An If condition checks if staffid = 0.

    1. The Then branch contains a CreateValidationItem activity with the following properties:

      Message "This staff user was not found"
      Messages formInstance.ValidationMessages
      MessageType Error
      Result <blank>

    2. The Else branch contains a GetEntity<StaffEntity> activity with the following properties:

      EntityId staffid
      Result staffEntity

  3. In the Next transition, check for a validation error to prevent the user from proceeding if the user's role does not match the role associated with the sequence. In the Condition field, specify not formInstance.ValidationMessages.HasErrors.

    Check for Validation Error

The following workflow segment checks if a user is permitted to access a student sequence. It creates a new student record if needed. The workflow denies access for staff users and prevents creating student records for users who logged in as staff.

AAD Student

  1. The Entry section of the first form contains a LookupUser activity with the following properties:

    UserId staffId
    UserName formInstance.UserName
    UserType Cmc.Nexus.FormsBuilder.Entities.UserType.Staff
    ValidationMessages formInstance.ValidationMessages

  2. An If condition checks if staffid > 0.

    This condition checks if a staff user is accessing a student sequence. The workflow prevents the staff user from running student sequence and ensures that if a new student attempts to create an account, a student record would not be created for a staff user.

    1. The Then branch contains a CreateValidationItem activity with the following properties:

      Message "Staff User Does Not Have Access to Run Student Sequence"
      Messages formInstance.ValidationMessages
      MessageType Error
      Result <blank>

    2. The Else branch contains a sequence with LookupUser activity for UserType=Student, followed by a condition that checks for a studentId, retrieves an existing StudentEntity or creates a Student Entity, and assigns required properties to the StudentEntity.

      AAD Student Only Check

      The Else branch contains a LookupUser activity with the following properties:

      UserId studentId
      UserName formInstance.UserName
      UserType Cmc.Nexus.FormsBuilder.Entities.UserType.Student
      ValidationMessages formInstance.ValidationMessages

      An If condition checks if studentId<=0.

      1. The Then branch contains a CreateEntity<StudentEntity> activity with the following property:

        Result studentEntity

        The following Assign activities are placed below the CreateEntity activity:

        To Value
        studentEntity.FirstName formInstance.UserInfo.FirstName
        studentEntity.LastName formInstance.UserInfo.LastName
        studentEntity.EmailAddress formInstance.UserInfo.EmailAddress
        studentEntity.CampusId formInstance.UserInfo.CampusId

      2. The Else branch contains a Get<StudentEntity> activity with the following properties:

        EntityId studentId
        Result studentEntity

      The following additional properties may need to be assigned to the StudentEntity below the Then and Else branches with the CreateEntity<StudentEntity> and GetEntity<StudentEntity>.activities.

      StudentEntity Properties

      *Assign values as appropriate for your environment.

      To Value*
      studentEntity.SchoolStatusId 1
      studentEntity.LeadDate datetime.Now
      studentEntity.IsActive true
      studentEntity.LeadSourceId 680
      studentEntity.AssignedAdmissionsRepId 2

  3. In the Next transition, check for a validation error to prevent the user from proceeding if the user's role does not match the role associated with the sequence. In the Condition field, specify Not formInstance.ValidationMessages.HasErrors.

    Check for Validation Error

For details about pre-populating formInstance.UserInfo variables when sequences are deployed in a cloud environment with Azure AD, see Azure AD Claims.

Login and Account Creation via Portal

For authenticated form sequences, Portal is used for both login and account creation and then control returns to Renderer. A page is displayed providing the option to log in using an existing Azure AD account or, if the user does not yet have an account, to create a new account. If "Create Account" is selected, the user will be redirected to the Portal.

login window

In Portal, the user will follow the steps to create an Azure AD account. The following fields are displayed when creating a new account:

  • Campus
  • First Name
  • Last Name
  • Email address
  • Username
  • Password
  • Security questions - if configured (e.g., Place of Birth, etc.)

Upon completion of the "Create new account" page, a new Azure AD account and Portal account (WpUser) will be created, and the user will be redirected back to the Portal login page.

The Login Locale setting can be used to add a drop-down list for locales on the Azure AD login page. For more information, see Login Locales.

If the "Create Account" option is selected on the Azure AD login page, the user is directed to the "New Account Creation" page in Portal. The header bar in Portal has a "Choose language" drop-down that is not linked to the Login Locales setting.

Renderer Web.Config Changes

When Forms Builder is installed in an Azure AD environment, the <issuers> section in the Forms Renderer web.config file will contain an "accountCreation" attribute that holds the Portal account creation URL.

    <!-- STS or Azure AD redirect URLs -->
    <issuers>
      <!-- <url key="A mapping issuerKey" 
					  value="An STS or Azure AD Login URL" 
					  accountCreation="If Azure AD, the portal account creation URL, otherwise empty" /> -->
      <url key="Student STS" accountCreation="<Portal account creation URL>" value="https://<server>.<domain>:<port>" />
      <url key="CRM STS" accountCreation="" value="https://<server>.<domain>:<port>" />
    </issuers>

Additional Renderer web.config changes may be necessary if the workflows for your authenticated forms (e.g., RFIs) use formInstance.UserInfo variables. For more information, see Azure AD Claims.

When Forms Builder is installed on premises, authentication of users is handled by the Security Token Service (STS) component.

  • Users of sequences associated with the Student/Contact role are authenticated by the Student STS for Anthology Student or by the Contact STS for CampusNexus CRM.

  • Users of sequences associated with the Staff role are authenticated by the Staff STS.

The authentication token returned by the STS identifies the user's role. The token enables the user to log in to Portal and access authenticated sequences as Student/Contact or Staff.

Forms Builder 3.4 and later can also be deployed in a cloud (Azure) environment with Active Directory (AD) authentication. In this environment, the STS component is not used. In an Azure AD environment, the authentication process does not allow for role verification.

The logic to verify the user's role must be embedded in all form sequences that are deployed in an Azure AD environment. Each workflow must include a LookupUser activity with UserType=Student or UserType=Staff as appropriate. The LookupUser activity with a proper UserType value ensures that student users cannot access staff sequences and vice versa.

Workflow Examples

When sequences for Staff and Student roles are deployed in an Azure AD environment, the workflows need to include logic as detailed below. These workflow segments need to be placed in the first form of a sequence.

For staff sequences we recommend creating a landing page that does not display any information intended for staff users only. The landing page should display a validation error if an unauthorized user (i.e., student) tries to access the staff sequence.

The following workflow segment checks if a user is permitted to access a staff sequence. It checks for a valid staffid.

AAD Staff

  1. The Entry section of the first form contains a LookupUser activity with the following properties:

    UserId staffid
    UserName formInstance.UserName
    UserType Cmc.Nexus.FormsBuilder.Entities.UserType.Staff
    ValidationMessages formInstance.ValidationMessages

  2. An If condition checks if staffid = 0.

    1. The Then branch contains a CreateValidationItem activity with the following properties:

      Message "This staff user was not found"
      Messages formInstance.ValidationMessages
      MessageType Error
      Result <blank>

    2. The Else branch contains a GetEntity<StaffEntity> activity with the following properties:

      EntityId staffid
      Result staffEntity

  3. In the Next transition, check for a validation error to prevent the user from proceeding if the user's role does not match the role associated with the sequence. In the Condition field, specify not formInstance.ValidationMessages.HasErrors.

    Check for Validation Error

The following workflow segment checks if a user is permitted to access a student sequence. It creates a new student record if needed. The workflow denies access for staff users and prevents creating student records for users who logged in as staff.

AAD Student

  1. The Entry section of the first form contains a LookupUser activity with the following properties:

    UserId staffId
    UserName formInstance.UserName
    UserType Cmc.Nexus.FormsBuilder.Entities.UserType.Staff
    ValidationMessages formInstance.ValidationMessages

  2. An If condition checks if staffid > 0.

    This condition checks if a staff user is accessing a student sequence. The workflow prevents the staff user from running student sequence and ensures that if a new student attempts to create an account, a student record would not be created for a staff user.

    1. The Then branch contains a CreateValidationItem activity with the following properties:

      Message "Staff User Does Not Have Access to Run Student Sequence"
      Messages formInstance.ValidationMessages
      MessageType Error
      Result <blank>

    2. The Else branch contains a sequence with LookupUser activity for UserType=Student, followed by a condition that checks for a studentId, retrieves an existing StudentEntity or creates a Student Entity, and assigns required properties to the StudentEntity.

      AAD Student Only Check

      The Else branch contains a LookupUser activity with the following properties:

      UserId studentId
      UserName formInstance.UserName
      UserType Cmc.Nexus.FormsBuilder.Entities.UserType.Student
      ValidationMessages formInstance.ValidationMessages

      An If condition checks if studentId<=0.

      1. The Then branch contains a CreateEntity<StudentEntity> activity with the following property:

        Result studentEntity

        The following Assign activities are placed below the CreateEntity activity:

        To Value
        studentEntity.FirstName formInstance.UserInfo.FirstName
        studentEntity.LastName formInstance.UserInfo.LastName
        studentEntity.EmailAddress formInstance.UserInfo.EmailAddress
        studentEntity.CampusId formInstance.UserInfo.CampusId

      2. The Else branch contains a Get<StudentEntity> activity with the following properties:

        EntityId studentId
        Result studentEntity

      The following additional properties may need to be assigned to the StudentEntity below the Then and Else branches with the CreateEntity<StudentEntity> and GetEntity<StudentEntity>.activities.

      StudentEntity Properties

      *Assign values as appropriate for your environment.

      To Value*
      studentEntity.SchoolStatusId 1
      studentEntity.LeadDate datetime.Now
      studentEntity.IsActive true
      studentEntity.LeadSourceId 680
      studentEntity.AssignedAdmissionsRepId 2

  3. In the Next transition, check for a validation error to prevent the user from proceeding if the user's role does not match the role associated with the sequence. In the Condition field, specify Not formInstance.ValidationMessages.HasErrors.

    Check for Validation Error

For details about pre-populating formInstance.UserInfo variables when sequences are deployed in a cloud environment with Azure AD, see Azure AD Claims.

Login and Account Creation via Portal

For authenticated form sequences, Portal is used for both login and account creation and then control returns to Renderer. A page is displayed providing the option to log in using an existing Azure AD account or, if the user does not yet have an account, to create a new account. If "Create Account" is selected, the user will be redirected to the Portal.

login window

In Portal, the user will follow the steps to create an Azure AD account. The following fields are displayed when creating a new account:

  • Campus
  • First Name
  • Last Name
  • Email address
  • Username
  • Password
  • Security questions - if configured (e.g., Place of Birth, etc.)

Upon completion of the "Create new account" page, a new Azure AD account and Portal account (WpUser) will be created, and the user will be redirected back to the Portal login page.

Renderer Web.Config Changes

When Forms Builder is installed in an Azure AD environment, the <issuers> section in the Forms Renderer web.config file will contain an "accountCreation" attribute that holds the Portal account creation URL.

    <!-- STS or Azure AD redirect URLs -->
    <issuers>
      <!-- <url key="A mapping issuerKey" 
					  value="An STS or Azure AD Login URL" 
					  accountCreation="If Azure AD, the portal account creation URL, otherwise empty" /> -->
      <url key="Student STS" accountCreation="<Portal account creation URL>" value="https://<server>.<domain>:<port>" />
      <url key="CRM STS" accountCreation="" value="https://<server>.<domain>:<port>" />
    </issuers>

Additional Renderer web.config changes may be necessary if the workflows for your authenticated forms (e.g., RFIs) use formInstance.UserInfo variables. For more information, see Azure AD Claims.