Single Sign On (SSO)

Note: Single-sign on is available with Service Pack F or later (20.2.64.8730).

With single sign-on, a user logs in with a single username and password and can navigate through multiple applications without ever needing to log back in. To configure single sign-on with iMIS and your third-party applications, you will first need to set up your application in iMIS, then add the client application redirect (Single Sign On content item) to a page.

Understanding Single Sign On: FAQ

Can users log into the third-party system first, or do they need to login to iMIS first?

Because iMIS is the membership application, you must log into iMIS first. SSO will not work if you log in to the third-party application first.

You can configure iMIS so that after a member is logged in, they are redirected to the page with the SSO content item and have the content item redirect the user to the non-iMIS site.

Is it possible for a user to log into a third-party application using the iMIS log-in page and then be redirected back to the third-party system once iMIS logs them in?

Not at this time.

If a user is first signed into iMIS and then goes to a third-party website, how is iMIS going to verify their previous authentication?

The authentication is done via an OAuth2 refresh_token that is specific to the user. The refresh token is used to gain bearer access tokens from the /token endpoint. They do not need the end user’s credentials for this as long as the refresh token is valid. When the refresh token expires, the end user will need to log back into iMIS and click on their redirect link into the client application.

How is Single Sign On implemented?

Single Sign On uses OAuth2 authorization tokens. Once configured, iMIS will pass a refresh token to the client application. The refresh token granted to the client application will be used, along with the client application’s credentials, to grant access tokens on behalf of the user logged into iMIS. The client application will manage the local login, but can store this token in a cookie, or in an authorization middleware of their choosing.

How does Single Sign On work?

Single Sign On in iMIS works as follows:

A GET is made to the content record containing the Single Sign On content item.
The content item redirects to the configured URL with a POST containing a refresh_token.
The redirected page then POSTS to the token end point with

grant_type=refresh_token
client_id=[id configured in the SSO content item]
client_secrect=[secret configured in the SSO content item]

The response from the Token request contains the access_token.
The returned access_token can then be used by subsequent calls where the access_token value is a bearer token in the Authorization header.

Is there a sample SSO redirect page?

Yes. The following drop-down is an example of the type of code needed for an SSO implementation.

Warning! The test page is not intended to be repurposed or used in a real production environment. This information is for demonstrative purposes only.

Click for details

<%@ Page Language="C#" AutoEventWireup="true"  %>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" >
<head runat="server">
<title>iMIS Single Sign On</title>
<style>
table 
{border-collapse: collapse;
}
table, td, th 
{border: 1px solid black;
}
td {
border-spacing: 2px;
padding: 10px;
}
</style>
</head>
<body>
<p>
The <a href="iSamples/SharedContent/SSODemo.aspx">iMIS Content record</a> containing the Single Sign-On iPart redirected to this page.
Here are a few notes about this flow:
</p>
<ul>
<li>You must be logged in to the iMIS system before selecting the link for the content record containing the Single Sign-On iPart.</li>
<li>The Single Sign-On iPart for this example is configured to use the <b>DemoSSO</b> client application, which has a refresh token lifetime of 25 minutes.</li>
<li>The <b>DemoSSO</b> client application can be viewed in
the <a href="https://tenant1.i10/imisMain10/Staff">staff site</a> at <b>Settings &gt; Contacts &gt; Client applications</b>.</li>
<li>If the access_token lifetime expires, you can use the refresh_token to obtain another access_token value.</li>
<li>If the refresh_token lifetime expires, you will need to go to the iMIS content record to generate a new refresh_token value and redirect back to this page.</li>
</ul>
<table>
<tr>
<td>
<form runat="server">
<h1>Step 1:  Arrive at this page</h1>
<p>The iMIS SSO iPart has redirected to this page.</p>
<h4>refresh_token: <asp:TextBox id="myRefreshToken" width="250" runat="server" /></h4>
<img src="https://www.freeiconspng.com/uploads/green-arrow-png-8.png" width="50px" height="50px" />
<br/>
<h1>Step 2: Obtain an access_token</h1>
<p>This is typically done by 'back-channel' (server-to-server) communication.</p>
<h4>REST API address: <asp:TextBox id="myRestAPIUrl" width="300" runat="server">https://progers.asi.local/imismain10_8405</asp:TextBox>
<h4>client_id: <asp:TextBox id="myClientId" width="100" runat="server">DemoSSO</asp:TextBox></h4>
<h4>client_secret: <asp:TextBox id="myClientSecret" width="120" runat="server">DemoSSOSecret!1</asp:TextBox></h4>
<input runat="server" type="button" onClick="document.getElementById('resultLog').innerHTML = '';GetAccessToken()" value="Obtain access_token" />
<br/>
<div id="tokenResultsDiv" style="visibility:hidden">
<h4>token_type: <asp:TextBox ID="tokenType" runat="server" /></h4>
<h4>expires_in: <asp:TextBox ID="expiresIn" runat="server" /> seconds</h4>
<h4>access_token:</h4>
<asp:TextBox TextMode="multiline" Columns="80" Rows="10" ID="accessToken" runat="server" />
<br/>
<img src="https://www.freeiconspng.com/uploads/green-arrow-png-8.png" width="50px" height="50px" />
<br/>
<h1>Step 3: Obtain data from iMIS for the logged-in user</h1>
<input type="button" onclick="GetPartyById()" value="GET Party data for PartyId"/>&nbsp;
<asp:TextBox ID="partyId" runat="server">19295</asp:TextBox>
<div id="getPartyResultsDiv" style="visibility:hidden">
<h4>Full name: <asp:TextBox ID="PartyFullName" width="300" runat="server" /></h4>
<h4>Address: <asp:TextBox ID="PartyFullAddress" width="500" runat="server" /></h4>
</div>
</div>
</form>
</td>
<td style="vertical-align: top;">
<h3 style="text-align: center">Log</h3>
<asp:Literal id="resultLog"></asp:Literal>
</td>
</tr>
</table>
</body>
</html>
<script type="text/javascript">
var resultLog = document.getElementById('resultLog');
function getDateTime()
 {var d = new Date();
var months = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
var hours = d.getHours().toString().length === 1 ? '0' + d.getHours() : d.getHours();
var mins = d.getMinutes().toString().length === 1 ? '0' + d.getMinutes() : d.getMinutes();
var seconds = d.getSeconds().toString().length === 1 ? '0' + d.getSeconds() : d.getSeconds();
return d.getDate() + " " + months[d.getMonth()] + " " + d.getFullYear() + " " + hours + ":" + mins + ":" + seconds;
}
function log(msg) {
resultLog.innerHTML += "<br/>" + getDateTime() + " - " + msg;
}
function GetAccessToken() {
var xhttp = new XMLHttpRequest();
var refreshToken = document.getElementById('myRefreshToken').value;
xhttp.onreadystatechange = function() {
if (this.readyState === this.DONE) {
log(this.status + " status received.");
if (this.status === 200) {
document.getElementById('tokenResultsDiv').style = "visibility:visible";
document.getElementById('accessToken').value = response.access_token;
document.getElementById('tokenType').value = response.token_type;
document.getElementById('expiresIn').value = response.expires_in;
log("Copying access_token and related info.");
} else if (this.status === 400) {
log("Potentially incorrect client_id and/or client_secret credentials, or possible refresh_token expiration."
+ "<br/>Ensure the credentials are correct or select the <b>iMIS Content record</b> link at the top of the page to obtain a new refresh_token.");
}
else {
log("Unexpected HTTP status: " + this.status);
}
}
};
var dest = GetRestApiUrl() + "/token";
var clientId = document.getElementById('myClientId').value;
var clientSecret = document.getElementById('myClientSecret').value;
var body = "grant_type=refresh_token&refresh_token=" + refreshToken + "&client_id=" + clientId + "&client_secret=" + clientSecret;
log("POSTing refresh_token to " + dest + " to obtain the access_token...");
log("Body='" + body + "'." )
xhttp.open("POST", dest, true);
xhttp.setRequestHeader("Content-type", "www/x-www-form-urlencoded");
xhttp.send(body);
}
function GetRestApiUrl() {
return document.getElementById('myRestAPIUrl').value;
}
function GetPartyById() {
var xhttp = new XMLHttpRequest();
xhttp.onreadystatechange = function() {
if (this.readyState === this.DONE) {
log(this.status + " status received.");
if (this.status === 200) {
document.getElementById('getPartyResultsDiv').style = "visibility:visible";
var response = JSON.parse(this.responseText);
log("Displaying some Party data for PartyId " + response.PartyId + ".");
document.getElementById('PartyFullName').value = response.PersonName.FullName;
document.getElementById('PartyFullAddress').value =
response.Addresses.$values[0].Address.FullAddress;
}
else if (this.status === 401) {
log("Using refresh_token to obtain another access_key...");
GetAccessToken();
log("Try to get the Party data again when the POST command completes.");
} else if (this.status === 404) {
log("Ensure the specified Party Id is correct.");
} else {
log("Unexpected HTTP status: " + this.status + ".  Ensure the specified Party Id is correct.");
}
}
};
var partyId = document.getElementById('partyId').value;
var dest = GetRestApiUrl() + "/api/Party/" + partyId;
log("Performing GET to " + dest + " with access_token set as a bearer token in the Authorization header...");
xhttp.open("GET", dest, true);
xhttp.setRequestHeader("Content-type", "application/json");
xhttp.setRequestHeader("Authorization", "Bearer " + document.getElementById('accessToken').value);
xhttp.send();
}
</script>
<script runat="server">
void Page_Load(object sender, EventArgs e)
{
myRefreshToken.Text = Request.Form["refresh_token"];
}
</script>

Does anything need to be completed on the third-party side?

Yes. In addition to the iMIS setup, additional coding is required on the third-party side to create a local login (client ID and client secret) and a strategy to accommodate the refresh tokens to request access tokens. After the additional coding is completed, the non-iMIS site can then make API calls to obtain and display the iMIS information. The third-party client application must also support OAuth2.

What contact details are inherited from iMIS after the user clicks on the redirect link to the third-party application?

The user is only authorized authenticated, and no contact details are inherited. If you would like additional contact details to be inherited, a custom bridge must be built.

Configuring Single Sign On

To configure single sign-on with iMIS and your third-party applications, do the following:

From the Staff site, go to RiSE > Maintenance > Client applications.
Select Add client application.
Enter the Client ID. This can be any name you choose. The name should reference the third-party application you are creating a link to. This name cannot be edited after the client application is saved.
Enter the Client secret. The Client secret is used to authenticate the application's identity to iMIS upon an access token request and should not be publicly shared.
In the Refresh token lifetime (minutes) field, enter the expiration of newly generated refresh tokens. This value determines the length of time a token is valid for in making authorization requests against iMIS between initial granting and expiration. When the refresh token expires, the user must return to iMIS and go back through the login flow.
Enter the Login redirect URL. This is the link to the third-party application, and where the user will be taken.
Click Save.

Next, add the Single Sign-On content item to a content record:

From a content record, select Add content.
Open the Contact folder, then select the Single Sign-On content item.
Give the content item a Name.
Select the Client application.
Click OK, then click Save & Publish.
Continue the process for each necessary client application.

The content record that the content item is added to does not need to be a publicly accessible content record, but it cannot be deleted. It is recommended to keep the content record in a secure folder.

You can add the redirect link to any location in your iMIS website. When the link is clicked, the contact will remain logged in with their same iMIS credentials.