Proprietary Single Sign-On workflow details

The proprietary single sign-on (LoginSSO) workflow consists of the following:

The user logs in to the utility website using the currently implemented mechanism.
The username is retained in either a session variable, cookie, or in another format.
This username or a generated version of it (so long as it is consistent each time) will be passed on to the LoginSSO service.
A link is placed in the utility website that leads to either a separate page or client-side code to facilitate communication with the portal. For example, if using JavaScript, there can be an AJAX call to the REST service to obtain the token.

Important! A prerequisite for this workflow is to create a service user account in the Itron Analytics database. The LoginSSO web service is secured using basic authentication, passing the username and password to authenticate that the web service is being called from the utility website. This is an application-to-application authentication process, so the utility website end user’s credentials are never passed. In fact, the end user’s userid passed for each call does not require an accompanying password. Instead, the service user account becomes an application-level set of credentials that are base-64 encoded before being sent and used to authenticate every call to the LoginSSO web service. The best way to create this service account is to use the Customer Portal registration page to register a user. This page requires the user to specify an account number, first name, last name and meter number as identifying information for completing the registration. After the user is created, the additional information such as account, first name, email, etc. will not be used during the application-level authentication process- only the username and password will be encoded and sent. For more information about the registration page, see "Customer Portal" in the Itron Analytics Analytics Portal Online Help. The username and password that are used during the registration are passed in the http authentication header when calling the LoginSSO web service.
LoginSSO is an operation on the Customer Portal User web service. This is a REST web service with the following URL: http://localhost/PortalServices/api/User/LoginSSO. The LoginSSO interface of the REST service only accepts calls via HTTP POST, so whatever method is used (server-side or AJAX), it must be done via POST. For example:
Copy
```
POST http://localhost/AnalyticsCustomerPortal/PortalServices/api/User/LoginSSO HTTP/1.1
Host: localhost
Connection: keep-alive
Content-Length: 140
Authorization: Basic dXNlcm5hbWU6cEBzc3cwcmQ=
Origin: http://localhost
Accept: application/json, text/javascript, */*; q=0.01
{ 
  "Username":"jsmith",
  "Email":"john.smith@email.com",
   "Accounts":[
     {"AccountID":"A1"},
     {"AccountID":"A2"}
    ],
  "FirstName":"John",
  "LastName":"Smith"
}
```
The value in the authorization header is the base-64 encoded username:password of the service account.

Important! The password parameter is not the end user’s password from the utility website. The end user’s password is never transmitted to, or stored in, the Customer Portal. Optionally, the utility can also elect to generate a username for the user that is different from the username on the utility portal, so that no exact details are passed at all – the only requirement is that the generated username be the same each time the user clicks the link to log in to Customer Portal.

The web service accepts a JSON document that has the following fields:
- Username. Identifies the user logging into the portal. If the username already exists in the Customer Portal, the portal updates the account association, first name and/or last name and email address with the newer values. If a user with this username does not exist, it is created. This process avoids maintaining two separate user databases. The information is synchronized automatically. If this value is null or empty, the process will fail. In addition, this username can be any consistently generated value from the utility website code (meaning on each successive use, it remains the same). It does not need to be the exact username in use on the utility website, which completely decouples maintenance of user details between the two databases and provides for better overall security.
- Email. The email address associated with the username. If the username does not exist, this value is saved as the email address. If the username does exist, it is compared with the existing entry and will overwrite any value that differs. This is not a required value to log in through SSO. However, without a valid email address, the daily and monthly alerts will not work, and the account management dialog is not available to SSO users.
- Accounts/AccountID. The list of account IDs associated with the username. These accountIDs must match accounts in the Customer Portal database or the process will fail. The user will be able to access the specified accounts in the Customer Portal. The list of account IDs can change in subsequent calls to the web service, and the Itron Analytics database will be updated to reflect the new user account assignments (including add/remove).
- FirstName/LastName. The first and last name of the Customer Portal user. If these values are not provided, the account holder's first and last name are automatically pulled from the account record and displayed.
The web service performs the activities described in Configuring proprietary Single Sign-On.
The web service returns a session token.
The utility website software creates a form post to the portal page, which contains the session token. This is the preferred method for passing the token to the portal because it hides the token from the URL line and removes a potential hacking method. However, the token expires in two minutes, and after the token is used to authenticate the user, it is immediately rendered invalid. Therefore, this extra security is optional.

Important! For some platforms, a form post may not be a feasible option, so sending the token via URL line (or HTTP GET) is allowed. The variable name for POST/GET is the same. The script must initiate a form post with the token as "ULoginToken" to the Customer Portal URL, or append "?ULoginToken=<token value>" to the portal URL and browse to it. The parameters on the URL do not display for very long, they are "cleared" during the login process. Also, the token is expired as soon as it is used, so it could never be used in an attack after the GET is received by the Customer Portal
The URL can also contain additional parameters to indicate which account and/or service point will be pre-selected when the Customer Portal page is initially displayed. The variable names for these parameters are "acctid" and "spid". For example, https://localhost/AnalyticsCustomerPortal?ULoginToken=23343&acctid=A1&spid=SP1.
The Customer Portal validates the session token against the database. If the token is found in the list and has not yet expired, the process will continue. If the token is missing or expired, the SSO login fails, and the user is returned to the Customer Portal login page with an error message. Most often, this is due to an expired token or a mismatch between the times on the server clocks.
The expiration date is set to one minute in the past to prevent it being used again. That way, even if someone does manage to gain possession of one of the login tokens, it cannot be used to enter the Customer Portal.
If the token is valid for entry, the userid is set on the thread so it will automatically pass by the forms authentication in IIS used by the Customer Portal. Then, the portal page is returned to the browser with appropriate usage data from the user’s account.
The Customer Portal page is displayed with the specified account and/or service point pre-selected.