Not logged in - Login
< back

SDK Authentication & SSO

Contents [hide]

Authentication & SSO using SIMS ID and OAuth2.0

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 removespage barriershas tobeen access,replaced andby 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 includedinformation in the configurationEducation ofSoftware theServices sampleTechnical 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 SI . 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

The Sample Client is of no use without the keys, secrets, scopes and URIs. How to obtain these is detailed below

 UsefulIntegrator 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 the 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:

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


Sandbox Environment

We provide a sandbox environment for you to test your integrations. The details are:

Live Environment

The details are:

Endpoints

  • 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

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.  We also allow additional scopes to be requested:

  • simsapplication †

    • Required to access a single organisation focused application. This scope can only be obtained by users who have authenticated with an identity provider and are known as a SIMS ID user. When a user signs into an application but is known to be associated with multiple schools the STS is expected to offer them a choice of school and populate the userorganisationidentifier claim appropriately.

  • simsmultiorgapplication †

    • Required to access multiple organisations in an unstructured way, or where there is no relationship between the organisations required for the application to function.
  • offline_access
    • Used by a requesting client to request a Refresh Token.

The scopes marked with † are mutually exclusive. The application should be clearly defined and only request one of these scopes..

Claims

The following claims are issued by the STS dependent on the scopes requested.

ClaimScopes Description
userorganisationidentifierssimsmultiorgapplicationIdentifies the user and organisation that a user is considered to be logged into. Typically used by applications that are focused on single school / organisation. Typically these applications are for use by school staff. There will only be a single value associated with this claim.
userorganisationidentifiersimsapplicationIdentifies the set of organisations that a user is associated with and their SIMS external ID within each organisation. Typically used by applications that are focused on interactions across small numbers of multiple where a parent is likely to have children at multiple organisations and wishes to view data from them in a joined up fashion. There can be multiple values associated with this claim. Each value takes the same format as the userorganisationidentifier claim. The resulting array of claims will be limited to 10. If the user has access to more than 10 organisations then the calling application can query SIMS ID to retrieve the full organization list.
applicationidsimsapplication simsmultiorgapplication The ID of the application that retrieved the token.
idpAll scopes The underlying identity provider as supplied by the identity provider itself.
nameAll scopesName of the user
multipleorganisationsAll scopesBoolean value that is used to identify if the User is a member of multiple
providerAll scopesIdentifies the identity provider
provideridAll scopesThe Users identifier for the provider
siteAll scopesContains the Organisation’s identifier code. For schools this is their DfE Code, for other Organisations this is a unique defined code a a maximum of 8 chars in length.
userorganisationidentifier and userorganisationidentifiers Claims

These claims identify a user at an organization and the type of that organisation. To prevent issues with misaligned arrays the claims take a compound format as shown below:

{userid}|{organisationid}|{organisationtype}

The component parts are as follows:

ComponentTypeDescription
useridGuidThe ID of the user as understood by all Capita and Partner Management systems (the SIMS External ID).
organisationidGuidThe ID of the organisation within SIMS ID
organisationtypeStringA string that contain multiple characters with each character in the sequence representing an organization type as described below..

Organisations can be of the following types.

CodeMeaning
CCapita
GSchool Group
LLocal Authority
MMulti Academy Trust
OSupport Organisation
SSchool

Examples

The following sequence represents a user (c498…) at organization (a87b…) that is a School:

c498dcbc-6832-4872-bbd3-1cc7072c57d5|a87b917e-9e52-440e-aebc-f48de5463597|S

The following sequence represents a user (a9ab…) at organization (99af…) that is a Multi Academy Trust:

a9abb2ca-342c-4bdd-94b7-cc6c4a98c6de|99af4670-8ad6-473d-97cb-79b396255c16|M

The following sequence represents a user (…) at organization (…) that is both a Multi Academy Trust and a School:

8aad423b-4058-4a45-b06c-8dc8e72de5a0|88fedc13-3a68-4ea1-94fb-053f8abafe88|MS

Requesting Clients

In order to integrate with us, you will need to request clients to be created for you in our Sandbox and Live environments.

We will need the following information for each client:

  • Authorization Flow
  • Scopes you require
  • Redirect URIs (URI’s you wish users to redirect back to after a successful authentication).
    • These can be localhost addresses in the sandbox environment
  • Any identity provider restrictions. For example, you may wish to only allow SIMS ID login, and not allow any users to log in using external providers such as Facebook.
  • Is Consent Required: currently this is set to off in our sandbox environment, however this will be turned on for your live environment client
  • Allow Remember Consent: this allows the above to be persisted for the user
  • Logout Session Required: Specifies if the user’s session id should be sent to the Logout Uri
  • Require Sign Out Prompt: when logging out you get a prompt screen asking to confirm you want to log out, before actually logging out
  • Contact for client ownership. This is the contact we will send the following information to:
    • The details Client Id and Secret will be encrypted in a password protected 7zip compressed file.
    • The compressed file will be sent to client owner(s) – the details at this point can be sent to multiple people
    • The password for the compressed file will then sent to the single client owner

When you are ready to request your client(s), please send the details to simsidteam@capita.co.uk

  • 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.

Refreshing Claims

During a session the access_token will occasionally require refreshing in order to obtain the latest set of claims.

Two approaches are required for this depending on the scenario.

Native Application

In October, 2017, the Internet Engineering Task Force (IETF) released the Best Current Practices (BCP) when using OAuth 2.0 with native mobile applications.

Native applications should use the AuthorisationCodeWithProofKey flow, which uses PKCE.

Web (SPA) Application

A single page web application should not hold on to a refresh token and therefore should use the silent token refresh approach using an invisible iframe to contact the token endpoint and specifying a prompt of none[1].

Long Lived Sessions

Access tokens should have short lifetimes however this can impair the user experience if users are required to frequently log in. One of the following approaches should be adopted for obtaining a new access token and transparently extending a session.

Native Application

A native application should obtain a refresh token that it can then use with the token endpoint to generate a new access token on expiry of that token.

Web (SPA) Application

A single page web application should use the silent token refresh approach to obtain a new access token shortly (2 minutes typically) before the access token is due to expire.

Restrictions on Clients

A small number of restrictions are placed on clients retrieving tokens from the STS.

  • The HTTPS protocol must be used for all communication. The STS should reject redirect URIs that do not use this protocol and any incoming requests that do not user this protocol.
  • When deployed in the live environment (as opposed to the instance used in the development environment) the STS will reject localhost based redirect URIs

Token Structure

The token structure as defined in JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and Authorization Grants Section 3.2 requires the sub claim to be defined differently depending on grant type.

Multi-factor Authentication

Multi factor authentication can be configured by each organization in SIMS ID.

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.

Shibboleth 2.0 endpoint that supports WAYFless

You can review our endpoint attributes by using the UK Federation Test Service Provider at https://test.ukfederation.org.uk/ and specifically, the test Service provided for the UK Federation Central Discovery Service

A WAYFless URL can also be generated using the UK Federation WU-GEN service

The metadata provided by the SIMS ID Shibboleth endpoint can be seen at Live https://sso.sims.co.uk/metadata Staging [https://r4csso.identityfor.co.uk/metadata]

SDK Authentication Modes

SDK Main Page | Authentication & SSO | Provisioning Integration | SIMS ID a stable integration platform