iSAMS SSO setup

Prerequisites

1. Your school should have been added to the Esenda portal
2. You should have an account with organisation administrator level access

Getting to the Identity Provider setup page in the Esenda portal

1. Log in to the Esenda portal at https://portal.esenda.com/
2. Click the three dots in the top right > "Settings":

3. Select the Identity Provider section on the settings list:

4. You will now be shown your Identity provider setup details. These will be what you need to copy into iSAMS in the next step:

Creating an SSO client in iSAMS

1. Click the three dots in the bottom left of the screen and click "Open Control Panel":

2. Click "Authentication":

3. Click "Manage SSO Clients":

4. Click "Create SSO Client":

5. Use the identity provider setup details you got from the Esenda portal to fill out the required details (substitute the values in this screenshot for the values you see in the portal).

6. Select the "Scopes" tab, and use the "Add scope" dropdown to add the "email" scope, it should look like this when this has been done:

7. Select the "Whitelist URIs" tab, and then select the URI type "Allowed Post Login Redirect URIs":

8. In the URI field, paste the value from the "Allowed Post Login Redirect URIs" field of the Identity Provider setup details screen (again, substitute in the value you can see in the Portal, don't use the value in the below screenshot)

9. Click "Add URI", after you've done that it should look something like this:

10: Hit "Save & Close"

11: You will now be shown your Client ID and Client secret. Make sure to make a note of these in a secure place, as the Client Secret cannot be viewed once this popup has been closed:

Adding the iSAMS SSO client to the Esenda Portal

1. On the Identity Provider Setup details screen, click "Continue":

2. You will now be shown the screen where you can provide the information Esenda needs to connect to iSAMS. Paste the Client ID and Client Secret you made a note of when adding the SSO client in iSAMS into the fields on this screen:

3. Provide the value for the "Issuer URL" field

The value here will be based on the domain that you use to access iSAMS. It should match the pattern:

https://<your-isams-domain-here>/auth

Note the /auth     at the end, it's important to include this:

4. Click "Submit"

5. If the identity provider is successfully added, you'll be shown this status screen:

6. Click the three dots in the top right > "Logout":

7. When you land on the login page again, you can now click "Login with SSO":

8. Type your organisation shortcode in and click "Verify". NOTE: If you're not sure what your shortcode is, log back in with your non-sso user and follow the steps here:

10. You will now be shown the iSAMS sign in screen if you're not already logged into iSAMS, so log in here as usual:

11. After logging into iSAMS, you will be redirected to the Esenda Portal home page. You're now logged in using SSO.

Inviting users to your Organisation

Before other users can sign in using the SSO Identity Provider, they will need to be invited to the organisation via user management.

Why do I need to invite users if I'm signing in with SSO?

Esenda needs to be able to verify that users actually own and have access to the email addresses that are tied to an external SSO identity provider. This way we know that someone is who the identity provider tells us they are. It also ensures that users have a functional password recovery flow if they need it.

The second reason that users need to be invited is so that the organisation administrator can define the permissions that users should have.

How to invite users

1. Click the three dots in the top right > "Settings":

2. Select the "User Mangement" section on the settings list:

3. Click "Create new user":

4. Fill out the user email and permissions as needed, then click "Create user":

5. The user will receive an invitation email

Steps for users to carry out when they get an invite email

1. They should navigate to https://portal.esenda.com/ and use the one time password in their invite email to log in:

2. The user should set their permanent password:

3. Then the user should set up MFA:

3. Once this is done, the user will be able to signed in using their non SSO user. They should now logout again:

3. The user will be able to log in using SSO. We will automatically deactivate the original portal user the first time someone signs in with SSO. This ensures that users are not switching between the two logins, and they just use SSO.

Adding the Esenda portal as a module in iSAMS

Once the Identity provider has been added in the portal and your users have been invited to the organisation, you can add the Esenda portal as a module inside iSAMS. You'll want to make sure you know your organisation shortcode before you do this.

Finding your organisation shortcode

1. Click the three dots in the top right > "Settings":

2. Select the "Account Information" section on the settings list:

3. Your organisation shortcode will be visible under the "Shortcode/Alias" field:

Adding the Esenda Portal as a module in iSAMS

1. Click the three dots in the bottom left of the screen and click "Open Control Panel":

2. Select "Modules & Programmes":

3. Select "Accounts":

4. Click "Create New Module":

5. On the "Module Details" tab, set the "Module Path" value to be:

https://portal.esenda.com?shortcode=<your-organisation-shortcode-here>

The rest of the fields can be set like so:

6. On the "Module Permissions" tab, make sure all permissions are enabled:

7. On the "Module Options" tab, make sure to enable the following options:

8. Click "Save & Close":

9. Reload iSAMS by clicking the arrow icon in the top right:

10. Click the grid Icon in the top left:

10. Click on the "Accounts" category

10. Click the Esenda Portal module:

11. A popup window will open, and the user will automatically be signed in to the Esenda Portal using SSO

Removing the Identity Provider from your organisation

Following these steps will remove the configured Identity Provider from your organisation. Doing this will disable all logins using that identity provider, and re-activate the non-IDP portal user accounts tied to your organisation.

1. Click the three dots in the top right > "Settings":

2. Select the "Identity Provider" section on the settings list:

3. Click "Delete Identity Provider":

4. Click "Confirm delete"

Troubleshooting

If a user sees this message when they try to log in:

Your account does not have access to this organisation. Please contact your organisation administrator to request access.

Then the user needs to be invited to the organisation via user management. See: Inviting users to your Organisation

If a user sees this message when they log in:

Your email address has not been verified. Please verify your email address before signing in.

Then they have been invited to the organisation by the administrator, but they have not completed the sign in process. See: Inviting users to your Organisation