SDK : Integrating with SIMS ID
Intended Audience
The SDK information is aimed at development teams from 3rd party integrators, content providers and Capita development teams.
Document Purpose.
This document provides information on the capabilities of the SIMS ID product from the perspective of how it may be utilised by other development and project teams. It details how they may benefit from a consolidated user authentication service that is common to end users across a range of Capita products. It also provides details on how development teams may use this service to accelerate their adoption of Identity Management services.
Why use identity Management from SIMS ID?
Available to all SIMS customers with no annual charge, SIMS ID is at the heart of Capita SIMS identity and authentication approach for SIMS and SIMS Partner products, providing a single identity per user that spans all products making access simple for the user. SIMS ID allows schools to automatically provision users to Google and Microsoft Office 365 from their SIMS Data
Identity Management – the Capita SIMS Approach
Capita believes that Identity Management (IdM) is fundamental to security when providing access to multiple disparate applications, and is central to the user experience being simple and positive.
At the heart of Capita’s approach to Identity Management is SIMS ID. SIMS ID is Capita’s flagship product for Identity Lifecycle Management, Authentication and Single Sign On. Sitting as a key component in Capita’s ‘Next Generation’ education products, SIMS ID is also available direct to SIMS 7 customers.
Security is at the heart of SIMS ID automatically extracting data from SIMS. Without the need to run reports or extracts, SIMS ID lets your data empower your staff and pupils to access a range of services. Based on the latest identity management technologies, SIMS ID creates a single identity for each user that is provisioned into our Identity Management solution, along with selected cloud services such as MS Office 365 and/or Google Apps. This is done without the need to expose or link your local network to Microsoft or Google, whilst still allowing your users to access the full feature sets provided by these systems. Put simply, SIMS ID takes the user data you enter into SIMS as part of your normal working practice, and automatically provides user accounts into your local AD, central AD and selected cloud services, with minimal delay and no fuss.
SIMS ID is also capable of synchronising group memberships (e.g. MIS classes) and other data (e.g. MIS timetables) with integrated systems in order to synchronise sites, distribution lists and providing the option for timetables to be displayed directly into Google or Office 365 calendars.
Passwords are often the weak link in any system security. SIMS ID aids in keeping your data secure by enforcing a sensible level of password complexity and password changes, while enabling the user to manage their own identity through self-service account administration and allowing the user to change and recover lost passwords simply and securely. A greater level of account administration can be delegated to key staff or members of your support organisation. Recognising that different users require different levels of security, multiple password policies can be enforced to allow young users to have easy to remember passwords without compromising the complex password requirements of users who have greater security privileges. Two factor authentication is high on the priority list for customers using SIMS ID to create and manage their AD accounts, and the ‘holy grail’ of single sign on is achieved: A single user name and password to sign into the computer and from their single sign-on to local and cloud systems. Outside of the site, the same username and password are used to access available cloud services including Capita Hosted SIMS for customers.
Developed to support industry standard claims based authentication to deliver federated identity services, SIMS ID is able to integrate with an increasing range of products provide by Capita and third-party providers. SIMS ID is designed to support more than just staff and pupils. Support for parent’s and other connected adults to access products is also built in - allowing, where appropriate, users to link other accounts such as Twitter or Microsoft accounts to their SIMS ID access. This removes the barrier to external users accessing systems and engaging with your services.
SIMS ID provides an engaging web based user interface to support administration of users and services as well as a tile based ‘launch pad’ for integrated applications and services. The look and feel of the ‘launch pad’ can be changed at each site; additionally ‘quick link’ tiles can be added as well as deploying additional services. SIMS ID is designed to work on a range of devices and browsers, rescaling the interface for use on the largest screens down to mobile devices and smart phones.
Figure 1- SIMS ID user and data provisioning
About SIMS ID
SIMS ID – two operating modes?
Depending on the context of the user and the available integrated sub-products, SIMS ID operates in one or more modes. At its most lightweight SIMS ID is a Security Token Service (STS) that provides a valid, signed token containing defined scope and claim information following a successful user authentication. At the opposite end of the continuum, SIMS ID is a highly featured user provision, management and authentication platform that unifies a range of Capita and third-party services under a Single Sign On regime. In this mode, the user provisioning agents can permeate both cloud services, central and local Active Directory (AD) structures.
Figure 2 - Headless (red arrows) and UI (blue arrows) authentication routes.
Headless
In this operating methodology the end user goes to an application URL directly and an example of this is Office 365. This application redirects the user to the SIMS ID Sign in page and upon successful authentication the user is redirected back the application.
This method is provided to allow a smooth user experience where the application is launched from embedded links in e-mail or other applications.
UI mode.
In the method, the user goes to https://id.sims.co.uk where they sign in. Upon successful authentication, a browser-dynamic User Interface (UI) is provided that allows the management of the SIMS ID system as well as providing a tile based launcher for SSO applications.
This is the most appropriate method where users may have more than one application secured by SIMS ID.
SIMS ID Design Structure.
Figure 3 - Elements of SIMS ID
STS
Based on an implementation of Identity Server, the SIMS ID STS service provides single sign-on and access control for modern web applications and APIs using protocols like OpenID Connect and OAUTH 2.0. It supports a wide range of clients like mobile, web, SPAs and desktop applications and is extensible to allow integration in new and existing architectures. The SIMS ID implementation is extended to provide a range of authentication sources, as well as extending SSO protocols to include Shibboleth, which is commonly used in the education and academic technology space. SIMS ID is a registered provider with the UK Access Management Federation.
Provisioning Agents
In addition to the provisioning and data exchange elements of OAUTH and the Edu Person specification leveraged through open standards such as Shibboleth and the SAML 2.0 interactions. SIMS ID has a number of extensible provisioning agents & APIS. This allows for provisioning to Active Directory, Office 365 and Google Applications; work is also currently underway on MS SDS to support MS Classroom. Where specific provision requirements are necessary, SIMS ID has a range of methods to call 3rd party scripts, APIs and applications.
Figure 4 - SSO and provisioning options
User Interface
SIMS ID can operate in two modes and though the underlying technologies are identical the user journey is different. Some integrations can be set to only operate through the UI mode and headless mode will also provide the option to operate via the UI.
Support tools
There is a separate interface that is provided for ‘high level’ support staff. This interface allows a range of support activities that are not designed for delegation down to customers support organisations or end users to be carried out.
The SIMS ID Architecture
Figure 5- SIMS ID Application Architecture
SIMS ID Localisation
The product is currently undergoing STS localisation initially with the Welsh Language, and this will be completed in Q1 2017. This work will confirm the localisation framework for the product is implemented in all areas of the core product. Further Language packs will be developed as business needs dictate.
Integrating with SIMS ID.
There are a range of integration options available with SIMS ID. Some are easily implemented, OAUTH for example, however others require a little more discussion. Here at SIMS ID we are always happy to discuss options to make it easy to integrate your application with our platform. We classify the two main types of integration as Authentication & SSO and User Provisioning
Authentication & SSO
SIMS ID can provide federated authentication services to your product providing a single sign-on (SSO) experience to joint customers, allowing them to use their familiar username and password to access your product. This removes barriers to access, and lessens the administration overhead associated with the adoption of a new service with its accompanying usernames and passwords.
This authentication can assert a number of attributes for the user, ranging from simply the site(s) they are associated with through to more complex person and relationship data.
Using OAUTH 2.0 and SAML 2.0 authentication integration is achieved using recognised standards and protocols
Sample Clients and Settings for OAUTH 2.0
Sample clients are available to aid in developing against the SIMS OPEN ID Connection Specification. The ZIP file below contains a sample client. Client configuration details that will need to be included in the configuration of the sample client app are available on request.
This is a sample Hybrid C# MVC Web Application that will need to be populated with specific test client details that will be provided for your organisation in the SIMS ID live environment. The SIMS ID SSO Partner agreement will need to be completed prior to going live. Where you are also a SIMS Partner, the organisation will be common to any developments you are doing against SIMS Primary APIs.
Download a sample client application
Useful information
The web.config details of the client will need to be filled in with your ClientId, scopes and our URI settings. You will need set your secret value. All of these settings will be provided following return of the SIMS ID Partner agreement.
The application is required to be run on https://localhost:5454. You will need to provide your hosting details so that the appropriate redirecturi settings for your client can be populated along with post logout redirect uri values. You will also need a test SSL certificate, however this can simply be a self-signed certificate installed for the application.
The sample app has a page “../Debug/Tokens” where you can see the Access and Identity tokens, this will assist you in your integration.
Useful Details for SSO integration:
Our OpenId .well-known endpoint can be found here: https://sts.sims.co.uk/.well-known/openid-configuration
STS Base URI: https://sts.sims.co.uk
Logout Endpoint = {STSBase}/connect/endsession
Token Endpoint = {STSBase}/connect/token
User Info Endpoint = {STSBase}/connect/userinfo
Identity Token Validation Endpoint = {STSBase}/connect/identitytokenvalidation
Token Revocation Endpoint = {STSBase}/connect/revocation
Settings (core ones of interest):
Consent Required : currently to off, this will be turned on for your Live client
Allow Remember Consent : allows the above to be persisted for the user
Logout Session Required : on logging out it will end the sessions
Require Sign Out Prompt : when logging out you get a prompt screen asking to confirm you want to log out, before actually logging out
Scopes:
openid
profile
roles
partner
All of the above are configurable and we can adjust to your needs, however the above is the most restrictive settings.
SIMS ID is based on IdentityServer3, and there is a large amount of resources available online. A good starting point is https://identityserver.github.io/Documentation/docsv2/resources/home.html
The following is bespoke to your implementation and will be provided by secure means:
Client Id
Client Name
Client Secret
This client is linked to your SIMS Primary organisation in the Live system you will have 2 users for:
Admin User: to be sent separately by secure mail
Staff User : to be sent separately by secure mail
The admin user can create user(s) in the site using the normal SIMS ID functionality, guide is available from the menu under the Users name.
SAML for SSO interactions
SAML integration outside of OAUTH 2.0 is not a preferred methodology, and we favour the OAUTH 2.0 approach. However, we can, and do, handle other SAML 2.0 interactions where necessary. Please contact to discuss your requirements.
Shibboleth for SSO interactions
Shibboleth can be supported.
UKAMF for SSO interaction
SIMS ID is registered with UKAMF.
Provisioning Integration
Limitations
SIMS ID does not provide all the data that exists within SIMS and it is not a replacement for the rich data available through the SIMS Partner programme’s APIs; SIMS ID can pass lightweight data suitable for user provisioning and group association; this data can also be passed securely using a range of protocols.
Approaches to Provisioning
SIMS ID has a provisioning API that exposes a subset of data; Access to this API is restricted to secured access using the SIMS ID STS.
The SIMS ID Provisioning API is defined by Swagger.
Swagger is a tool used to provide a list of SIMS ID APIs. This forms the API documentation and will be available on a public URL.
The following data (subject to agreement of the data controller) will be available for sites that are aligned with your product.
User information
Name
Groups/class/house/year
Age range eg <13 / >16
Unique ID
Site information
Name
DFE
Unique ID
SIMS ID a stable integration platform
SIMS ID SSO is based on Open Standards and the implementation of these standards and changes are closely governed.
For Authentication & SSO integrators.
The OAUTH 2.0 implementation by SIMS ID is based on the Principles of Open ID Connect - https://openid.net/connect/
SIMS ID maintains a SIMS ID specific version of the Open ID Connect Specification. This is updated periodically and circulated on ratification to current SIMS ID Partners. Any breaking changes within the specification will depreciated over one revision of the specification with minimum six month grace period.
The SIMS ID OPENID Spec.
Download the SIMS OPENID CONNECT SPEC V3.0.4
For provisioning integrators.
The SIMS ID Provisioning API is under semantic versioning of ‘current’ and ‘current-1’. The breaking change rate is currently once in 18 months.
Benefits of being a SIMS ID Partner
Simplified sign on to your application for your customers through SIMS ID
No passwords to manage
No password reset support calls
Secure standards based technologies
Reduced user admin for your customers
- Simple user provisioning direct from SIMS ID, with this data drawn directly from School MIS systems
Schools know your product is available through SIMS ID
Your application tile available to ALL or restricted sets of SIMS ID schools.
Licence management options to deploy your application tile to known customers
Authentication of users to your application
You control the sale and the revenue
Unlike other app stores you control the sales process.
For a limited time no commission is taken for sales generated.
Data from the best source of truth
Access to additional user attributes direct from SIMS ID, with this data drawn directly from the school MIS systems – for example: registration group data
SIMS ID takes its data directly from school MIS systems: SIMS Hosted and SIMS in schools. Other manufacturer’s MIS systems can also be supported
The ability to display the ‘Log in with SIMS ID’ logo and SIMS ID Partner Logos
- informing your customer base that they can simply work with your product through SIMS ID
Joint marketing opportunities.
Support for SIMS ID Partners
SIMS ID Partners may raise a support case by emailing simsidteam@capita.co.uk putting SIMS PARTNER SUPPORT at the beginning of the ‘subject’ line.
Please include full details and where appropriate to enable replication.
Please do not include any ‘keys’, ‘secrets’ or personal identifying data in any email communications with Capita SIMS ID.