SSO - Sample Client

SSO Sample Application

Sample clients are available to aid in developing against the SIMS OPEN ID Connection Specification.

The Sample Client is of no use without the keys, secrets, scopes and URIs.

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.  

Where you are also a  registered SIMS Integrator, the organisation will be common to any developments you are doing against SIMS Primary APIs,  DeX or any other API secured by SIMS ID

Client configuration details that will need to be included in the configuration of the sample client app are available on request via registering with the Integrator Registration Portal

 

How to Configure the SSO Sample App

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 to Partner Support so that the appropriate redirec turi settings for your client can be populated in the system along with post logout redirect uri values.

You will also need a test SSL certificate, however, for the purpose of developing your application 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.

Accessing the Sand Box Environment for SSO

As part of your Integrator Registration you will be assinged a 'Sandbox' Instance of the SIMS ID SSO endpoint to develop against.  Credentails for this service will be provided.

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

• STS Base URI: https://simsid-partner-stsserver.azurewebsites.net
• OpenId .well-known endpoint: https://simsid-partner-stsserver.azurewebsites.net/.well-known/openid-configuration

Live Environment

The details are:

• STS Base URI: https://sts.sims.co.uk
• OpenId .well-known endpoint: https://sts.sims.co.uk/.well-known/openid-configuration

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:

• partnermanagementapplication †

  • 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

Claim	Scopes	Description
userorganisationidentifiers	simsmultiorgapplication	Identifies 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.
userorganisationidentifier	partnermanagementapplication	Identifies 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.
applicationid	partnermanagementapplication simsmultiorgapplication	The ID of the application that retrieved the token.
idp	All scopes	The underlying identity provider as supplied by the identity provider itself.
name	All scopes	Name of the user
multipleorganisations	All scopes	Boolean value that is used to identify if the User is a member of multiple
provider	All scopes	Identifies the identity provider
providerid	All scopes	The Users identifier for the provider
site	All scopes	Contains 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.

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:

Component	Type	Description
userid	Guid	The ID of the user as understood by all ESS and Partner Management systems (the SIMS External ID).
organisationid	Guid	The 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

C	ESS.Ltd Company
G	School Group
L	Local Authority
M	Multi Academy Trust
O	Support Organisation
S	School

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 ess-partnersupport@parentpay.com.  

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