Authentication

Introduction

The CLS needs to know the identity of all existing Users who try to enter the system. Every time a User enters the CLS, they must go through authentication, that is, the process of proving identity. The manner in which they authenticate will vary depending on the configuration of the Authentication of the site. The CLS offers a number of methods of authentication, with the most commonly used ones being:

• A standard User Name in Database.
• Single Sign On (SSO) using Security Assertion Mark-up Language (SAML).

Both methods include a Custom Logout Url field, which specifies where Users go when they logout or are logged out of the CLS.

The authentication model is specified by navigating to Settings > Authentication.

Username in Database

In this model the identity and authentication information is held within the CLS. Users will access the site via a Login screen and will be required to use account details existing in the CLS.

SAML

The CLS supports single sign-on (SSO) using the SAML 2.0 protocol. Identity and identification information is held on a separate server, the Identity Provider.

With this system users can securely login to the CLS from within another user management system where they have already signed on. Thus, they can connect to the CLS within this single sign-on. The SAML system also allows:

• automatic creation and update of user information during authentication.
• passing of group membership information during authentication.

This means that the first time a SSO user reaches the CLS, s/he can be registered as new CLS User without the need for another form of new CLS User registration (such as a batch process User spreadsheet import performed by an administrator). This also means that the CLS can update existing User accounts based on Attribute Statements contained in the authentication process.

Note also that the Public Identity Provider setting can be used to make the browser check if the Identity Provider can be reached. If it cannot be reached, the CLS presents the standard CLS logon screen.

An example

The simplified diagram below shows one typical SAML scenario and a registered CLS User who is not already authenticated with the CLS. A high-level overview of the process is as follows. The user tries to access the CLS (1). The CLS determines that the appropriate authentication method is SAML and sends an authorisation request to the appropriate Identity Provider (2 & 3). If the User does not have an existing logon at the Identity Provider that meets requirements s/he is asked to provide valid credentials (4 & 5); if s/he does have the logon then steps 4 and 5 are unnecessary. The Identity Provider then sends a response to the CLS Assertion Consumer Service (6 & 7) and the resource requested is supplied (8), i.e. access to the CLS. The browser acts as the “broker” in these transactions.

More information about SAML

Security Assertion Mark-up Language (SAML) is an XML-based framework for communicating user authentication, entitlement, and attribute information. At a minimum SAML exchanges take place between systems entities referred to as:

These entities can play the following roles:

The ability for a SAML requester and responder to communicate relies upon trust relationship between the two entities having been previously been configured.

Janison SAML operates as the relying party in SAML interactions and refers requests to a third party Identity Provider operated by the client.

The SAML standard is developed and maintained by the Security Services Technical Committee of the Organisation for the Advancement of Structured Information Standards (OASIS), with the specifications at https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=security

SAML Profiles

SAML profiles define how the SAML assertions, protocols and bindings are combined and constrained to provide greater interoperability in different scenarios.

The following profiles are used by Janison SAML:

Web Browser SSO Profile

This defines how SAML entities use the Authentication Request Protocol and SAML Response messages and assertions to achieve single sign-on with standard web browsers. It defines how the messages are used in combination with the HTTP Redirect, HTTP POST and HTTP Artifact bindings.

The Profile defines two roles:

• an IdP or Identity Provider
• an SP or Service Provider role. Janison SAML plays this role.

Two general scenarios are supported in this profile:

• IdP initiated: the user first accesses the Identity Provider (IdP).
• SP initiated: the user first accesses the Janison system (SP).
  The previous diagram showed a SP initiated login by a registered CLS User who is not already authenticated.

Single Logout Profile

Once single sign-on has been achieved, several individual sessions with service providers share a single authentication context. The Single Logout Profile can be used to log out from Multiple Federated Service Providers at once. Janison SAML is able to:

• initiate a global logout or
• respond to a global logout.

Setting SAML configuration options

1. Create Users

If checked, the system will create new User accounts in the CLS when a user is authenticated via SAML and is not found in the database.

2. Update Users

If checked, will update existing User accounts based on Attribute Statements contained in the Identity Provider Authentication response.

3. Login Literal

Used to adjust the wording that is used to refer to the SAML Identity Provider. Often set to SSO, it can be useful to let users know which authentication service they’re using.

4. Identity Provider SSO URL

The URL for the Identity Provider Single Sign-on service

5. Identity Provider Logout URL

The URL for the Identity Provider Single Sign-out service.

6. Identity Provider Certificate File

The public certificate used to verify the signature on messages from the configured Identity Provider.

7. Signing Key File

The SSL Signing certificate used to sign Assertions made by this server when communicating with the configured Identity Provider.

8. Display Password

When checked, displays the password for the Signing Key File.

Attributes sets the mapping between supported properties in the Janison database and specific Attribute statements in the Identity Provider SAML response.

Groups makes it possible to link Attribute names with Group types and to specify whether old memberships are inactivated and/or new groups created as part of the Identity Provider SAML response.

User API

The Janison CLS has an application programming interface (API) endpoint with the ability to create and update users in the CLS based on a third party data source. For example, users created in an organisation’s HR system can be dynamically created and updated in the CLS.

Note that the user API ‘pushes’ data from third party software to the CLS. The CLS has a related method for ‘pulling’ data to the CLS using the HR import. You can read more about the feature in our users document.

There are two steps required for the setup of the API:

• Configure the CLS.
• Create an application which will act as the bridge between the third party software and the CLS. Creation of this application will require a developer with programming skills relating to integration.

Note: We have a sample file available which clients can use to base their development on. Please contact the support department for the Janison User API Sample.cs.

The API can only create or update a single user at a time. There is no support for bulk creating or updating users.

Workflow

Create a new Role

A new role is required to authenticate the API.

Browse to Settings > Roles

1. Select Add Role from the Actions dropdown.

2. Enter a Name and Identifier.
3. Enter a Description (optional).
4. Check Main Role.

5. Select Save Role.

Setting Securable areas of the Role

For the API to work, the Web Services securable areas need to be set in the Role. You can read more about securable areas in our document on Roles.

1. In the Securable areas of the application section of the newly created role select the  icon.

2. Expand Web Services.
3. Expand User.
4. Set Create or Update User to Allow.

Create a Janison API User

The Janison APIs need to be authenticated as a user. This user must have their main role set to the newly created Janison API role as detailed in the previous section.

Browse to Manage People > Users.

1. Select Add User from the Actions dropdown.

2. Enter the details for the new user.

Detailed steps to create users can be found in our documentation on Users.

In the System section select the newly created Role:

3. Select your new role, in this example, API Role from the Role dropdown.
4. Select All Organisations from the Scope of this role dropdown.

5. Select Save User.

Configure Janison APIs

Browse to Settings > Authentication.

1. Under Janison APIs, select Generate new key for the Primary and Secondary keys.
2. Select the API role created in the previous instructions.

One of these keys will be entered into the third party application.

This step ensures that only users with this role are allowed to authenticate with Janison API.

Create 3rd party application

Please contact your support team, or account manager to discuss the use of the API, and to obtain some sample code to get you started.