Difference between revisions of "AD links"

From InsightWiki
Jump to navigation Jump to search
 
(60 intermediate revisions by the same user not shown)
Line 1: Line 1:
−
===Configuration===
+
AD Links is an additional module in Insight. It allows users to log in to Insight using their Active Directory account. This is essential for student logins and optional for staff logins. <br> <br>
−
The AD links page is provided to allow the configuration of Insight to work with your Active Directory.
 
  
−
For student accounts, you can use existing Active Directory principals and create Insight accounts for them on first use.  The uniquely identifying field by default is the EmployeeID field, but as an alternative you can user the Pager field, if for example the EmployeeID is already used, or it is not practical to make it visible.
+
As AD Links is an additional module of Insight, a separate charge applies. Please contact <span class="plainlinks">[mailto:sales@tascsoftware.co.uk sales@tascsoftware.co.uk]</span> for further information. <br> <br>
  
−
For students the contents of this field can be either the SIMS database id, their Admission Number or their UPN.  For parents and staff, Insight accounts must be created beforehand, and the uniquely identifying field must be populated with the SIMS database id. 
+
=Configuration=
  
−
Additionally, Active Directory Security groups should be created for the purpose of allowing and denying access to Insight.
+
==Importing Identifying Numbers into Active Directory==
  
−
You will need to have licensed the AD Links option to access the page. You can check for this in Reports –Licences, and re-license from here if necessary.
+
An identifying number must appear in each AD record in order for Insight to link with the Active Directory. It is recommended to use the Admission Number for students, although the UPN or SIMS PersonID can also be used. For staff only the SIMS PersonID can be used. <br> <br>
  
−
The AD Links menu allows you to configure the link to your Active Directory database, by providing details of your domain and an account which can read it.  The most difficult part of configuring this is in getting the format of the options correct.
+
A list of staff PersonID numbers can be obtained from Insight. Go to: <br>
−
Firstly, make sure the '''Check in AD when logging in''' is turned ON!
+
''Accounts > AD Links'' <br>
−
The domain field should be in the form
+
Click the '''Staff report''' button to download a file containing the PersonID numbers for all staff. The file is in XML format but you can open it in Excel <br> <br>
−
    mydomain.local
 
−
The User Container should be in the form
 
−
    CN=Users,DC=mydomain,DC=local
 
−
The Domain reading user should be in the form
 
−
    mydomain\user
 
  
−
The '''...require membership of this Security Group''' should be the name of the Security Group alone and is sensitive to capitals.  If you want to allow a selection of different Security Groups (year based perhaps) separate them with ; (semi-colon) characters.
+
It is possible to use SIMS AD Provisioning to import Admission Numbers into the Active Directory for students. Alternatively you can use a script from TASC Software to perform this provisioning for you. The TASC script can also be used to import SIMS PersonID numbers for staff. The TASC script will enter the chosen identifying number into the EmployeeID field in Active Directory. <br> <br>
  
−
If all Students are to have identical Roles in Insight, enter the name. The alternative is to use * (asterix) to tell Insight to use the first matching Security Group name from the list that the user belongs to is to be used as the Insight Role
+
If you wish to use the TASC Software script you will need a CSV file called INPUT.CSV in the format. The file must have exactly two columns; the first column must show the AD Username and the second column must show the identifying number. <br> <br>
  
−
The default behavior of Insight is to use built in methods for obtaining a set of EmployeeID:Security Group records separated by the | (bar) character, but you can implement your own variation by providing an '''Override web service URL''' which can use the wildcards {username}, {domain} and {schoolno} in the overall URL. An example URL might look like this:
+
The script file can be downloaded here: '''<span class="plainlinks">[http://www.tascsoftware.co.uk/wiki/INSIGHT/files/import.vbs import.vbs]</span>''' <br>
−
https://internalservices/ADLookup.php?accountname={username}&domainname={domain}
+
(right click and select Save As to download) <br> <br>
−
The page should return plain text and list the contents of the EmployeeID field (or other lookup value) and relevant Security Group (or other control setting).
 
  
 +
Once you have downloaded the file, edit it in Notepad (right click and select Edit). The first line of the file will read: <br>
 +
CONST strDomain="MyDomain" <br> <br>
  
−
If you want to allow staff to use Active Directory based login you will need to turn the '''Allow staff role users to use delegated login''' on.
+
You need to edit this so that your domain appears between the quotation marks, instead of MyDomain. Save the file, then place it in a new folder with your CSV file. The folder must contain nothing else.
 +
<br>
 +
You will need to log on locally to your DC before running the VBS script.
 +
<br>
 +
Double click the import.vbs file to run the script which will update your Active Directory. <br> <br>
  
−
If you have problems implementing single sign on using Active Directory, temporarily switch on the '''Embed login trace in page (for testing only)''' option.  This will do two things – if you view the main login page with a developer tool, you can read debugging information out of the hidden input field with the id '''delegateresult''' which can help highlight any issued, and also a file “securewin.log” is written to the (normally) %windir%\TEMP\Insight folder with detailed information about the process.  Don’t forget to switch off this option when it is no longer needed.
+
==Settings within Insight==
  
−
For student users, you will have to tell Insight if the EmployeeID field represents something different than the SIMS database id, either Admission Number or UPN.
+
[[Image:ad_links_page.png|thumb]]
  
−
If you are to be using the Pager field in place of the EmployeeID field, turn the related option on too.
+
The following settings are entered into the AD Links page, which is accessed via: <br>
 +
''Accounts > AD Links'' <br> <br>
  
−
'''Important'''
+
'''Check in AD when logging in''' must be enabled for Active Directory logins (if this is switched off, all AD logins will be disabled). <br> <br>
−
After updating the AD links details you will also need to set
 
−
  '''Manage – Preferences – Login – Trust this host as an authentication provider'''
 
−
to the short name of your domain.
 
  
−
==Seamless login==
+
Next enter the '''Domain''', '''Domain reading user''' and '''Domain reading password''' fields. <br>
−
An additional benefit of using this method to log in is that it supports Integrated Windows Authentication in supported browsers. This means that if the user is logged onto a computer within the domain, their account information can be used to log seamlessly into Insight, without requesting them to enter their account details by hand.
+
The domain should be in the form: mydomain.local. Click the '''Check''' button when you have entered these details to confirm that Insight can access the Active Directory. <br>
−
To enable this, all of the previous settings must be working correctly.
+
''In some cases you may see a message reading "A trust relationship does not exist between ..."; This should not cause any issues or be a cause for concern.'' <br> <br>
  
−
Where the web domain is the same as the network domain, or you are using an application gateway, you can use either of the methods below.  Otherwise you should use only the first.
+
By default Insight will check the EmployeeID field for the Admission Number (ADNO) to identify students. This will also be required for staff if you want them to log in using the Active Directory details, but they do not have trusted login accounts in SIMS. <br> <br>
  
−
===Method 1===
+
Enable the '''Use alternative AD field in place of EmployeeID''' option if you would prefer to use an AD field other than EmployeeID. You then need to enter your choice of field into the '''Name of alternative field to use''' setting. <br> <br>
−
The simplest way to implement seamless login is to direct those users who you expect to be able to login to the ADSSO.aspx page initially. If the user is not already logged into the domain, they will be redirected the the normal login page, where they can still enter their Active Directory username and password.  Otherwise, depending on their Security Group membership, they will be passed straight through to Insight.
 
−
If you do not expect a user to be able to log in this way, they should be directed to the normal login URL.
 
  
−
===Method 2===
+
'''Use student email addresses from AD''' <br>
−
To implement this method, all users are directed to the normal Secure.aspx , you will need to "protect" the SecureWin.ASPX web page with Windows Authentication, whilst denying Anonymous Access.  The way to do this is by running the ServiceController program located within the INSIGHT folder of your main shared SIMS folder, and on the Application tab, check the option '''HTTP401 on SecureWin'''.
+
The alternative is to use the email addresses in SIMS <br> <br>
−
 
−
With this enabled, an out-of-band request is made by the main login page to this SecureWin page.  This page reacts in the following way:
 
−
*If Anonymous Access is enabled, the page returns emptiness, and the normal login screen is displayed. 
 
−
*If Windows Authentication is enabled instead, a domain credential is sent, checked and an encrypted user credential is returned back to the main login screen, which is automatically submitted, and the login proceeds normally.
 
  
−
The problem with enabling this on its own is that outside the domain, or where Integrated Windows Authentication cannot take place, a HTTP 401 challenge is returned, and a browse specific pop-up is shown, requesting domain based login details. To hide this you will need to make a change to the web.config file, changing the '''Expect_Authentication_Header_In_First_Request_To_SecureWin''' value to '''Yes'''. This setting will spot that a HTTP 401 status is being returned specifically for SecureWin, and blur this into a HTTP 403 status, which will not provoke the browser popup, but will be enough to show the normal login screen.
+
=Single Sign On=
 +
 
 +
An additional benefit of using this method to log in is that it supports Integrated Windows Authentication in supported browsers.  This means that if the user is logged onto a computer within the domain, their account information can be used to log into Insight seamlessly (e.g. without entering their account details again). <br> <br>
 +
 
 +
To implement seamless login, direct those users who you expect to be able to login using their Active Directory details to the ADSSO.aspx page initially. For example: <br>
 +
{|
 +
|Use this address:||<span style="color:#36b"><nowiki>https://insight.myschool.co.uk/ADSSO.aspx</nowiki></span>
 +
|-
 +
|Rather than this:||<span style="color:#36b"><nowiki>https://insight.myschool.co.uk/secure.aspx?ReturnUrl=%2f</nowiki></span>
 +
|} <br>
 +
 
 +
If the user is not already logged into the domain, they will be redirected to the normal login page, where they can still enter their Active Directory username and password. If you do not expect a user to be able to log in this way, they should be directed to the normal login URL. <br> <br>
 +
 
 +
=Troubleshooting=
 +
 
 +
==Accounts Not Linked==
 +
 
 +
Check on the Users page: <br>
 +
''Accounts > Users'' <br> <br>
 +
 
 +
The students' Insight accounts should include @DOMAIN (where DOMAIN is replaced by your AD domain). If any of the students' accounts do not contain this, then those accounts are not linked to the Active Directory and will not be able to log in. You can search for these accounts by filtering to see those where the username does not contain @. <br> <br>
 +
 
 +
If you find any accounts that are not linked to AD, then log in to Active Directory and check that the student's AD record has the correct identifying number in the correct field. If the AD record appears to be correct then log in to SIMS and check that the identifying number in AD is correct. Once the necessary corrections have been made, perform a '''[[User_management#Student|Synchronisation]]''' via the Users page. <br> <br>
 +
 
 +
==Activity Report==
 +
 
 +
If students' accounts are linked to the Active Directory but they are not able to log in using their AD details then visit the AD Links page via: <br>
 +
''Accounts > AD Links'' <br> <br>
 +
 
 +
Click the '''Activity Report''' button. This will open a window showing the most recent login attempts from AD linked users. This report will tell you if a user has entered an incorrect password. If a user's login attempt does not appear on this report then they are attempting to log in using a username that Insight does not recognise. <br> <br>
 +
 
 +
==Expose AD Fail==
 +
 
 +
There is a setting in the web.config file that can be changed, which will display information about the Active Directory on the login page. To enable this setting edit the web.config file for Insight, which is typically found via: <br>
 +
''C:\inetpub\wwwroot\INSIGHT\web.config'' <br> <br>
 +
 
 +
Near the bottom of the file is a setting called '''ExposeADFail'''. Set the value of this setting to Yes e.g.
 +
<setting name="ExposeADFail" serializeAs="String">
 +
  <value>Yes</value>
 +
</setting>
 +
 
 +
Once the value is set to Yes, save the file then attempt to log in to Insight using one of the AD accounts experiencing the problem. The login attempt and you will see a warning message on the login page such as "Invalid username". Hover over the warning message to see further details about the Active Directory connection and login attempt. <br> <br>
 +
 
 +
[[Category:Additional modules]]
 +
[[Category:Management]]
 +
[[Category:Technical]]

Latest revision as of 12:09, 28 October 2019

AD Links is an additional module in Insight. It allows users to log in to Insight using their Active Directory account. This is essential for student logins and optional for staff logins.

As AD Links is an additional module of Insight, a separate charge applies. Please contact sales@tascsoftware.co.uk for further information.

Configuration

Importing Identifying Numbers into Active Directory

An identifying number must appear in each AD record in order for Insight to link with the Active Directory. It is recommended to use the Admission Number for students, although the UPN or SIMS PersonID can also be used. For staff only the SIMS PersonID can be used.

A list of staff PersonID numbers can be obtained from Insight. Go to:
Accounts > AD Links
Click the Staff report button to download a file containing the PersonID numbers for all staff. The file is in XML format but you can open it in Excel

It is possible to use SIMS AD Provisioning to import Admission Numbers into the Active Directory for students. Alternatively you can use a script from TASC Software to perform this provisioning for you. The TASC script can also be used to import SIMS PersonID numbers for staff. The TASC script will enter the chosen identifying number into the EmployeeID field in Active Directory.

If you wish to use the TASC Software script you will need a CSV file called INPUT.CSV in the format. The file must have exactly two columns; the first column must show the AD Username and the second column must show the identifying number.

The script file can be downloaded here: import.vbs
(right click and select Save As to download)

Once you have downloaded the file, edit it in Notepad (right click and select Edit). The first line of the file will read:
CONST strDomain="MyDomain"

You need to edit this so that your domain appears between the quotation marks, instead of MyDomain. Save the file, then place it in a new folder with your CSV file. The folder must contain nothing else.
You will need to log on locally to your DC before running the VBS script.
Double click the import.vbs file to run the script which will update your Active Directory.

Settings within Insight

Ad links page.png

The following settings are entered into the AD Links page, which is accessed via:
Accounts > AD Links

Check in AD when logging in must be enabled for Active Directory logins (if this is switched off, all AD logins will be disabled).

Next enter the Domain, Domain reading user and Domain reading password fields.
The domain should be in the form: mydomain.local. Click the Check button when you have entered these details to confirm that Insight can access the Active Directory.
In some cases you may see a message reading "A trust relationship does not exist between ..."; This should not cause any issues or be a cause for concern.

By default Insight will check the EmployeeID field for the Admission Number (ADNO) to identify students. This will also be required for staff if you want them to log in using the Active Directory details, but they do not have trusted login accounts in SIMS.

Enable the Use alternative AD field in place of EmployeeID option if you would prefer to use an AD field other than EmployeeID. You then need to enter your choice of field into the Name of alternative field to use setting.

Use student email addresses from AD
The alternative is to use the email addresses in SIMS

Single Sign On

An additional benefit of using this method to log in is that it supports Integrated Windows Authentication in supported browsers. This means that if the user is logged onto a computer within the domain, their account information can be used to log into Insight seamlessly (e.g. without entering their account details again).

To implement seamless login, direct those users who you expect to be able to login using their Active Directory details to the ADSSO.aspx page initially. For example:

Use this address: https://insight.myschool.co.uk/ADSSO.aspx
Rather than this: https://insight.myschool.co.uk/secure.aspx?ReturnUrl=%2f


If the user is not already logged into the domain, they will be redirected to the normal login page, where they can still enter their Active Directory username and password. If you do not expect a user to be able to log in this way, they should be directed to the normal login URL.

Troubleshooting

Accounts Not Linked

Check on the Users page:
Accounts > Users

The students' Insight accounts should include @DOMAIN (where DOMAIN is replaced by your AD domain). If any of the students' accounts do not contain this, then those accounts are not linked to the Active Directory and will not be able to log in. You can search for these accounts by filtering to see those where the username does not contain @.

If you find any accounts that are not linked to AD, then log in to Active Directory and check that the student's AD record has the correct identifying number in the correct field. If the AD record appears to be correct then log in to SIMS and check that the identifying number in AD is correct. Once the necessary corrections have been made, perform a Synchronisation via the Users page.

Activity Report

If students' accounts are linked to the Active Directory but they are not able to log in using their AD details then visit the AD Links page via:
Accounts > AD Links

Click the Activity Report button. This will open a window showing the most recent login attempts from AD linked users. This report will tell you if a user has entered an incorrect password. If a user's login attempt does not appear on this report then they are attempting to log in using a username that Insight does not recognise.

Expose AD Fail

There is a setting in the web.config file that can be changed, which will display information about the Active Directory on the login page. To enable this setting edit the web.config file for Insight, which is typically found via:
C:\inetpub\wwwroot\INSIGHT\web.config

Near the bottom of the file is a setting called ExposeADFail. Set the value of this setting to Yes e.g. 

<setting name="ExposeADFail" serializeAs="String">
  <value>Yes</value>
</setting>

Once the value is set to Yes, save the file then attempt to log in to Insight using one of the AD accounts experiencing the problem. The login attempt and you will see a warning message on the login page such as "Invalid username". Hover over the warning message to see further details about the Active Directory connection and login attempt.

Retrieved from "https://www.tascsoftware.co.uk/wiki/INSIGHT/index.php?title=AD_links&oldid=6309"