Last modified by MasterApps Support on 2022/01/19 09:14
Show last authors
1 Injury Master has support for Single Sign-On (SSO) via the SAML 2.0 standard.
2
3 = Prerequisites {{id name="prerequisites"/}} =
4
5 You must provision your own third-party SAML 2.0 identity provider for use with this feature before you can enable SSO on your account.
6
7 = Setting Up Your Identity Provider {{id name="setting-up-your-identity-provider"/}} =
8
9 Injury Master supports identity providers that utilize the SAML 2.0 specification, such as Shibboleth and Active Directory Federation Services (ADFS) and Azure Active Directory.
10
11 The identity provider must be configured to trust the Injury Master service provider (sometimes called a 'relying party').
12
13 Most commonly this is performed by importing the service provider's (in this case Injury Master's) metadata XML into your identity provider.
14
15 == Active Directory Federation Services (Windows Server 2008 R2 - Window Server 2022) ==
16
17 === Step 1. Metadata {{id name="step-1.-metadata"/}} ===
18
19 The metadata XML describes the endpoints, certificates and bindings that the Injury Master service provider supports.
20
21 Injury Master's SAML 2.0 metadata XML can always be found at the following URL:
22
23 https://www.injurymaster.com.au/saml2/metadata/
24
25 It is best practice to register this URL with your identity provider in order to always have the latest values if things change, rather than performing a once off import or configuring manually.
26
27 **Enabling TLS 1.2 on an ADFS Server**
28
29 Injury Master uses TLS 1.2 and TLS 1.3 for secure communication with our application. Unfortunatately all versions of Windows Server (2022 and ealier) require TLS 1.2 to be enabled before metadata retrieval can occur. To enable TLS 1.2 enter the following commands into Power Shell as the Administrator user:
30
31 (% class="box" %)
32 (((
33 New-Item 'HKLM:\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols\TLS 1.2\Client' -Force | Out-Null
34 \\New-ItemProperty -path 'HKLM:\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols\TLS 1.2\Client' -name 'Enabled' -value '1' -PropertyType 'DWord' -Force | Out-Null
35 \\New-ItemProperty -path 'HKLM:\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols\TLS 1.2\Client' -name 'DisabledByDefault' -value 0 -PropertyType 'DWord' -Force | Out-Null
36 \\New-ItemProperty -path 'HKLM:\SOFTWARE\Microsoft\.NetFramework\v4.0.30319' -name 'SchUseStrongCrypto' -value '1' -PropertyType 'DWord' -Force | Out-Null
37 )))
38
39 **Example: Importing Metadata for ADFS 2.0 on Windows 2008 R2**
40
41 1. Open the ADFS 2.0 Management Console.
42 1. Under Trust Relationships > Relying Party Trusts, select "Add Relying Party Trust..".
43 [[image:Attachments.WebHome@Windows_Server_2008_Enterprise_R2__Running_.8dcbf.png||style="max-width:527px"]]
44 1. The Add Relying Party Trust Wizard will appear. Click "Start" to continue.
45 1. Enter IM's metadata XML into the "Federation metadata address".
46 [[image:Attachments.WebHome@Windows_Server_2008_Enterprise_R2__Running_.37162.png||style="max-width:556px"]]
47 1. Click "Next" for all remaining dialogs of the Wizard.
48
49 === Step 2. Name Identifier {{id name="step-2.-name-identifier"/}} ===
50
51 Injury Master's SAML 2.0 service provider supports the following common Name ID types:
52
53 * Email Address (urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress)
54 * Persistent (urn:oasis:names:tc:SAML:2.0:nameid-format:persistent)
55 * Transient (urn:oasis:names:tc:SAML:2.0:nameid-format:transient)
56
57 You can select which type you wish to use in the SSO provider settings (see below in Setting Up Injury Master).
58
59 Regardless of the Name ID you wish to use, Injury Master must always be provided with the email address of the user (if not via Name ID, then via attributes, see the Identity Attributes section below). This will be used to link to the correct user account within Injury Master.
60
61 **Example: Using a Email Address Name ID for ADFS 2.0 on Windows 2008 R2**
62
63 1. Open the ADFS 2.0 Management Console.
64 1. Select the Injury Master relying party and click "Edit Claim Rules...".
65 [[image:Attachments.WebHome@Windows_Server_2008_Enterprise_R2__Running_.f409e.png||style="max-width:319px"]]
66 1. On the "Issuance Transform Rules" tab, click "Add Rule...".
67 1. Select "Send LDAP Attributes as Claims" and click "Next >".
68 1. Name the rule "E-Mail-Addresses to E-Mail Address", select the attribute store as "Active Directory", map "E-Mail-Addresses" to "E-Mail Address" and click "Finish".
69 [[image:Attachments.WebHome@Windows_Server_2008_Enterprise_R2__Running_.a5b90.png||style="max-width:348px"]]
70 1. Click "Add Rule..." again and select "Transform an Incoming Claim" and click "Next >".
71 1. Name the rule "E-Mail Address to Name ID", select "E-Mail Address" as the incoming claim type, "Name ID" as the outgoing claim type, "Email" as the outgoing Name ID format and click "Finish" to add the rule.
72 [[image:Attachments.WebHome@Windows_Server_2008_Enterprise_R2__Running_.0e485.png||style="max-width:313px"]]
73
74 **Example: Using a Persistent or Transient Name ID for ADFS 2.0 on Windows 2008 R2**
75
76 Follow the steps outlined at the following MSDN blog:
77
78 http://blogs.msdn.com/b/card/archive/2010/02/17/name-identifiers-in-saml-assertions.aspx
79
80 === Step 3. Identity Attributes {{id name="step-3.-identity-attributes"/}} ===
81
82 Identity Attributes (sometimes called 'claims') are attributes that are provided to Injury Master when the user logs in.
83
84 Injury Master makes use of the following attributes:
85
86 **Email Address**
87
88 Can be one of the following:
89
90 * mail (urn:oid:0.9.2342.19200300.100.1.3)
91 * email (urn:oid:1.2.840.113549.1.9.1.1)
92 * email (urn:mace:dir:attribute-def:email)
93 * emailAddress (http:~/~/schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress)
94 * emailAddress (urn:mace:dir:attribute-def:emailAddress)
95
96 //Important: The email address is required when using a Persistent or Transient Name ID//
97
98 **First Name**
99
100 Can be one of the following:
101
102 * givenName (urn:oid:2.5.4.42)
103 * givenName (http:~/~/schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname)
104 * givenName (urn:mace:dir:attribute-def:givenName)
105 * gn (urn:mace:dir:attribute-def:gn)
106
107 **Last Name**
108
109 Can be one of the following:
110
111 * sn (urn:oid:2.5.4.4)
112 * sn (urn:mace:dir:attribute-def:sn)
113 * surname (http:~/~/schemas.xmlsoap.org/ws/2005/05/identity/claims/surname)
114 * surname (urn:mace:dir:attribute-def:surname)
115
116 **Example: Providing Email and Name attributes as a Claim for ADFS 2.0 under Windows 2008 R2**
117
118 1. Open the ADFS 2.0 Management Console.
119 1. Select the Injury Master relying party and click "Edit Claim Rules...".
120 [[image:Attachments.WebHome@Windows_Server_2008_Enterprise_R2__Running_.f409e.png||style="max-width:319px"]]
121 1. On the "Issuance Transform Rules" tab, click "Add Rule...".
122 1. Select "Send LDAP Attributes as Claims" and click "Next >".
123 1. Name the rule "Get E-Mail and Name".
124 1. Assign the following LDAP attributes to the following Claim Types and then click "OK":
125
126 * E-Mail-Adressess -> E-Mail Address
127 * Given-Name -> Given Name
128 * Surname -> Surname
129
130 [[image:Attachments.WebHome@Windows_Server_2012__Running_.0cb26.png||style="max-width:561px"]]
131
132 === Step 4. (Optional) Single Log Out Query String Fix for ADFS 2.0 under Windows 2008 R2 {{id name="step-5.-single-log-out-query-string-fix-for-adfs-2.0-under-windows-2008-r2"/}} ===
133
134 If you are using anything other than ADFS on Windows Server 2008 R2 then you can skip this step.
135
136 IIS has an issue with the length of the Single Log Out (SLO) SAMLRequest query string. You can fix it by following the steps outlined in this guide:
137
138 https://googlegroups.com/group/canvas-lms-api-users/attach/27cd3bf9af3124a/ADFSSingleLogOutWorkaround.pdf?part=4
139
140 = Setting Up Injury Master {{id name="setting-up-injury-master"/}} =
141
142 After your identity provider has been configured, the next step is to configure Injury Master itself.
143
144 == Step 1. Enabling Single Sign On {{id name="step-1.-enabling-single-sign-on"/}} ==
145
146 To enable Single Sign On, log in with an Administrator account and go to Settings > Users & Permssions.
147
148 Click on the more drop down on the "Add User Account" button and select "Manager Single Sign On (SSO)".
149
150 [[image:Attachments.WebHome@User_Accounts.d3d32.png||style="max-width:302px"]]
151
152 **Metadata URL**
153
154 Enter your identity providers metadata URL into the Metadata URL input.
155
156 For ADFS under Windows Server, this will likely be:
157
158
159 {{code}}
160 https://yourdomain.com/federationmetadata/2007-06/federationmetadata.xml
161 {{/code}}
162
163 **Enabled Domains**
164
165 Specify the email domains, separated by a comma, that will log on via SSO.
166
167 For example, if you had users with the email addresses bob@domain1.com and jane@domain2.com that you wanted to sign in via SSO, then you would enter the following as the enabled domains:
168
169
170 {{code}}
171 domain1.com,domain2.com
172 {{/code}}
173
174 **Name ID Format**
175
176 As described in "Setting Up Your Identity Provider" above, select the name ID format your identity provider wishes to use.
177
178 [[image:Attachments.WebHome@Single_Sign_On.81560.png||style="max-width:310px"]]
179
180 After saving your changes you will see observe Injury Master attempting to contact your identity providers metadata and retrieve it. If successful you will see a message similar to the following:
181
182 [[image:Attachments.WebHome@Single_Sign_On.25785.png||style="max-width:268px"]]
183
184 == Step 2. Adding Users {{id name="step-2.-adding-users"/}} ==
185
186 After you have successfully enabled SSO on your account, you can now add your SSO users.
187
188 Simply add user accounts as you normally would, specifying each users email address as the same email address that is registered with your identity provider.
189
190 SSO users will be marked as such, as seen below, and only SSO users will be able to log in via SSO.
191
192 [[image:Attachments.WebHome@User_Accounts.e406e.png||style="max-width:289px"]]
193
194 == Step 3. Signing In {{id name="step-3.-signing-in"/}} ==
195
196 The final step is to test signing in via SSO.
197
198 On the Sign In page, select the "Enterprise" tab and enter your Account ID before clicking "Continue".
199
200 Your Account ID is the unique name in your account's URL. For example:
201
202
203 {{code}}
204 https://www.injurymaster.com.au/youraccountid/
205 {{/code}}
206
207 [[image:Attachments.WebHome@Sign_In_-_Injury_Master.d30a6.png||style="max-width:330px"]]
208
209 You will then be redirected to your identity provider and prompted to sign in.
210
211 Your SSO setup is now complete!

Child Pages

XWiki