Using SSO to Sign In

This article explains how single sign-on (SSO) works in Virtual Superintendent when using an external identity provider.

Virtual Superintendent supports SSO using OpenID Connect (OIDC) through AWS Cognito.

What is single sign-on (SSO)?

Single sign-on (SSO) allows users to access multiple systems using one set of login credentials.

Users sign in through your organization’s identity provider. After authentication, they can access Virtual Superintendent without signing in again.

What are the benefits of SSO?

Using SSO provides the following benefits:

• Your organization controls authentication and security policies
• Users sign in once and access Virtual Superintendent without additional login steps
• Users do not need to manage multiple usernames and passwords

How the SSO process works in Virtual Superintendent

Virtual Superintendent uses AWS Cognito to manage authentication. Cognito connects to your identity provider using OIDC.

The following steps describe the typical OIDC flow.

Step 1. User signs in to your identity provider

The user signs in to your organization’s identity provider, such as Azure Active Directory. The identity provider verifies the user’s credentials.

Step 2. User accesses Virtual Superintendent

The user opens Virtual Superintendent or selects a link from your internal system. Virtual Superintendent redirects the user to the identity provider if they are not already authenticated.

Step 3. Identity provider returns authentication data

After successful authentication, the identity provider returns an authentication response to AWS Cognito.

This response includes:

• An ID token
• User identity attributes such as email and name

Step 4. Cognito validates the response

AWS Cognito:

• Verifies the authentication token
• Validates the user identity
• Maps the user to an existing Virtual Superintendent account

Step 5. Virtual Superintendent signs in the user

If the user account exists and is active:

• The system creates a session
• The user is signed in to Virtual Superintendent

Required configuration for OIDC

To configure OIDC, the following values must be provided:

• openid-configuration URL
• client_id
• client_secret

Your identity provider must return:

• email
• name

Optional attributes which will be consumed if provided:

• given_name
• family_name

Configuration values for production:

• redirect platform: Web
• redirect uri: https://auth.myvirtualsuper.com/oauth2/idpresponse

Configure Azure Active Directory for OIDC

Follow these steps to register and configure an application in Azure Active Directory (Azure AD) for use with Virtual Superintendent.

Step 1. Register a new application

To register the application:

1. Sign in to the Azure portal.
2. Open Microsoft Entra ID.
3. Select App registrations.
4. Click New registration.
5. Enter the application name as My Virtual Super.
6. Select the appropriate account type for your organization (for example, My organization only).
7. Click Register.

Step 2 Configure application branding

To configure branding and properties:

1. Open the registered application.
2. Select Branding & properties.
3. Enter the following values:

• Name: My Virtual Super
• Homepage URL: https://www.myvirtualsuper.com/
• Privacy statement URL: https://www.thevirtualsuperintendent.com/privacy-policy

4. Upload the logo using this file: https://csl-images-prod.s3.ap-southeast-2.amazonaws.com/VS-Logo.png

Step 3. Configure redirect URL

1. Select Authentication.
2. Click Add a platform.
3. Select Web.
4. Enter the redirect URI: https://auth.myvirtualsuper.com/oauth2/idpresponse
5. Click Save.

Step 4. Create client credentials

Step 5. Get the OpenID configuration URL

To locate the OpenID configuration URL:

1. Select Endpoints from the application overview.
2. Copy the OpenID Connect metadata document URL.

Example:

https://login.microsoftonline.com/<tenant-id>/v2.0/.well-known/openid-configuration

Step 6. Verify publisher domain

To verify the publisher domain:

1. Copy the Application ID.
2. Create a file named:

microsoftidentity-association.json

3. Upload the file to:

https://www.myvirtualsuper.com/.well-known/microsoftidentity-association.json

Next actions

After completing these steps, provide the following values to configure OIDC in Virtual Superintendent:

• openid-configuration URL
• client_id
• client_secret