Azure AD Claims

For authenticated forms, user information is captured in claims that are passed from the authentication service to Forms Renderer. You can extract user information from the claims and pass it to workflows using the formInstance.UserInfo variable. You can then use the values contained in the variable to pre-populate form fields such as first name, email, and user name.

The claims that are passed to Renderer are different depending on whether authentication is performed by Student/Contact STS or by Azure Active Directory (AD). Prior to the release of Forms Builder 3.4, the STS was the only authentication service available. The code for the formInstance.UserInfo variable was designed to work with the STS claims. The code does not automatically extract user information from claims passed by Azure AD. This means that any previously created authenticated forms with workflows that use formInstance.UserInfo variables will not provide the capability to pre-populate form fields with user information when deployed in a cloud environment with Azure AD.

However, the code for Forms Builder 3.4 allows overriding the claims in the web.config file of Renderer. These overrides map STS claims to Azure AD claims. The overrides prevent any existing workflows that rely on the formInstance.UserInfo variables from failing with null pointer reference errors in AzureAD environments.

The following default claim types from the Student STS are available:

CampusIdClaimType:         "http://schemas.xmlsoap.org/ws/2010/08/identity/claims/campusid"
EmailAddressClaimType:     "http://schemas.xmlsoap.org/ws/2010/08/identity/claims/email"
FirstNameClaimType:        "http://schemas.xmlsoap.org/ws/2010/08/identity/claims/fname"
FullNameClaimType:         "http://schemas.microsoft.com/identity/claims/displayname"
LastNameClaimType:         "http://schemas.xmlsoap.org/ws/2010/08/identity/claims/lname"
MiddleNameClaimType:       "http://schemas.xmlsoap.org/ws/2010/08/identity/claims/mname"
RoleClaimType:             "http://schemas.microsoft.com/ws/2008/06/identity/claims/role"
UserIdClaimType:           "http://schemas.xmlsoap.org/ws/2010/08/identity/claims/userid"
UserNameClaimType:         "http://schemas.xmlsoap.org/ws/2010/08/identity/claims/uname"

To override claims, you can add keys to <appSettings> section of Renderer web.config file. Use the claim type as the key and add your value. For Azure, the values are fixed, i.e., you must use the values as they are. For other environments, you can specify your own values to override any claim with anything you desire.

<add key="FirstNameClaimType" value="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname" />
<add key="EmailAddressClaimType" value="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name" />
<add key="UserNameClaimType" value="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name" />

With the overrides above added to the web.config of the Renderer in the Azure AD environments, the FirstName, UserName, and EmailAddress fields will be populated and accessible within the workflow using the formInstance.UserInfo variable.

The above limitation continues to occur when an Azure authenticated form sequence is integrated with Student Portal as an external link and is configured to be viewed as a pop-up or as a tab. The form sequence will be redirected to Azure for authentication and the above Azure AD claims will be used to populate the formInstance.UserInfo variable.

However, this limitation is overcome when the form sequence is launched within an iframe in Student Portal as an external link. The following information will be retrieved from the Student Portal web service (IntegrationServices/CMCIntegrationService.asmx) using the AuthGuid which is passed as a query string when the user clicks on the external link, thus enabling successful SSO login.

The following table lists mappings of the FormInstance.UserInfo variable to the Student Portal webservice response (ExternalAuthorization).

FormInstance.UserInfo Field	ExternalAuthorization Field Value
UserId	CampusPortalID
UserName	UserCode
FirstName	FirstName
LastName	LastName
MiddleName	Dummy
EmailAddress	Email
CampusId	CampusList[0]
Roles	RoleType
ExternalUserId	UserID

For details about designing sequences for authentication with Azure AD, see Azure AD Authentication.

For authenticated forms, user information is captured in claims that are passed from the authentication service to Forms Renderer. You can extract user information from the claims and pass it to workflows using the formInstance.UserInfo variable. You can then use the values contained in the variable to pre-populate form fields such as first name, email, and user name.

The claims that are passed to Renderer are different depending on whether authentication is performed by Student/Contact STS or by Azure Active Directory (AD). Prior to the release of Forms Builder 3.4, the STS was the only authentication service available. The code for the formInstance.UserInfo variable was designed to work with the STS claims. The code does not automatically extract user information from claims passed by Azure AD. This means that any previously created authenticated forms with workflows that use formInstance.UserInfo variables will not provide the capability to pre-populate form fields with user information when deployed in a cloud environment with Azure AD.

However, the code for Forms Builder 3.4 allows overriding the claims in the web.config file of Renderer. These overrides map STS claims to Azure AD claims. The overrides prevent any existing workflows that rely on the formInstance.UserInfo variables from failing with null pointer reference errors in AzureAD environments.

The following default claim types from the Student STS are available:

CampusIdClaimType:         "http://schemas.xmlsoap.org/ws/2010/08/identity/claims/campusid"
EmailAddressClaimType:     "http://schemas.xmlsoap.org/ws/2010/08/identity/claims/email"
FirstNameClaimType:        "http://schemas.xmlsoap.org/ws/2010/08/identity/claims/fname"
FullNameClaimType:         "http://schemas.microsoft.com/identity/claims/displayname"
LastNameClaimType:         "http://schemas.xmlsoap.org/ws/2010/08/identity/claims/lname"
MiddleNameClaimType:       "http://schemas.xmlsoap.org/ws/2010/08/identity/claims/mname"
RoleClaimType:             "http://schemas.microsoft.com/ws/2008/06/identity/claims/role"
UserIdClaimType:           "http://schemas.xmlsoap.org/ws/2010/08/identity/claims/userid"
UserNameClaimType:         "http://schemas.xmlsoap.org/ws/2010/08/identity/claims/uname"

To override claims, you can add keys to <appSettings> section of Renderer web.config file. Use the claim type as the key and add your value. For Azure, the values are fixed, i.e., you must use the values as they are. For other environments, you can specify your own values to override any claim with anything you desire.

<add key="FirstNameClaimType" value="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname" />
<add key="EmailAddressClaimType" value="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name" />
<add key="UserNameClaimType" value="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name" />

With the overrides above added to the web.config of the Renderer in the Azure AD environments, the FirstName, UserName, and EmailAddress fields will be populated and accessible within the workflow using the formInstance.UserInfo variable.

For details about designing sequences for authentication with Azure AD, see Azure AD Authentication.