DRAFT

Overview

Admin App v3.0 supports two methods for authentication: web-forms authentication or single-sign on via Open ID Connect (OIDC). Both utilize ASP.NET Core Identity as the underlying framework. This page will provide details to configure Admin App based on the selected model. Please use this as reference for Admin App v2.x, however the single-sign on via Open ID Connect method is not supported in those product versions.

Table of Contents

maxLevel	21

Admin App Roles

Admin App uses two roles within the application for ODS/API management. The Super-Administrator role is used to register multiple users with separate roles and privileges along with all ODS / API instances and its functions. The Administrator role is allowed to access only specific ODS / API instances and its functions. This user authentication model pairs well with multi-instance support within Admin App.

1. Super-Administrator (default role for the first user)

The Super-Administrator role is intended for an IT Administrator managing a collection of individual ODS instances, such as found within district collaboratives.

Super-Administrator Permissions

Add a user
Assign a role to an added user
Register and delete ODS / API instances
Change and assign an ODS / API instance to an added user
Change user settings for other users
Delete a user
Plus, all permissions of the Administrator role

2. Administrator

The Administrator role is one that can access one or more ODS instances assigned by the Super-Administrator. This means that users in the Administrator role can only administer ODS / API instances specifically assigned.

Administrator Permissions

Manage applications
API key/secret creation
View descriptors
Bulk data uploads
Learning standards synchronization

Securing Admin App

Existing form authentication (Please refer here for more details)
Single sign on (SSO)

Web Form Authentication

Click here to open Web Form Authentication setup instructions:

Toggle cloak

Cloak

First-Time Administrative User Setup

When first entering Admin App after installation, you must first register an initial Super-Administrator user. Click "Register as a new user" on login page for user registration.

The initial registered user automatically assigned with the “Super-Administrator” role. Provide an email, password, and confirm password value for login.

First-Time Admin App system setup

After user registration, the session will be directed to "Additional Setup Required" page for completing required steps. Click "Continue" to trigger the first-time setup process.

Once that is done, the user will be navigated to home page for the "Super Administrator" role with Global and ODS Instances icons.

Clicking on the Global icon will navigate to the Global page, where a user can administer Vendors, Claim Sets, and Users.

Details on ODS / API instance registration can be found here: Multi-Instance Connections (v2.0.1).

Additional User Setup

The Super-Administrator can manage additional users on Global→Users tab.

Valid email address and a temporary password are needed for creating an additional user.

Added user can be assigned with Super Administrator or Administrator role by "Edit User Role" action.

An added user can be assigned with ODS / API instances by "Manage ODS Instances" action.

User details can be edited with "Edit User" action.

A user can be deleted with "Delete user" action.

Added user will login with credentials provided by a Super-Administrator for the first time. After successful login, the user will be prompted to change their password.

If an added user is an "Administrator" then the Home page will be presented with the "ODS INSTANCES" icon.

Clicking on "ODS INSTANCES" icon will take user to list of assigned ODS API instances page.

No assigned ODS API instances:

With assigned ODS API instances:

Single

sign on:

Sign-On with Open ID Connect (Admin App v3.x+)

Click here to open Single Sign-On with Open ID Connect setup instructions:

Toggle cloak

Cloak

Abbr. OpenID Provider (OP)

Admin App SSO feature supports trusted 3rd party source as the source of identity for the application users.

Enabling single sign on:

To enable SSO on AdminApp, user needs to provide following appsettings values:

Code Block

title	Appsettings

IdentitySettings": {
        "Type": "OpenId",
        "OpenIdSettings": {
            "AuthenticationScheme": "oidc",
            "Authority": "",
            "ClientId": "",
            "ClientSecret": "",
            "UserProfileUri": "",
            "LoginProvider": "my-oidc-provider",
            "ResponseType": "code id_token",
            "RequireHttpsMetadata": false,
            "SaveTokens": true,
            "GetClaimsFromUserInfoEndpoint": true,
            "Scopes": [ "openid", "email" ],
            "ClaimTypeMappings": {
                "NameClaimType": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name",
                "IdentifierClaimType": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier",
                "EmailClaimType": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress",
                "RoleClaimType": "http://schemas.microsoft.com/ws/2008/06/identity/claims/role"
            }
        }
    }

Type: EntityFramework or OpenId

Default value is “EntityFramework” which enables form authentication. For enabling SSO, the type value will be set to “OpenId”.

Authority: Autherity URL for making openIdConnect calls.

ClientId: The client identifier from OP. This identifier is assigned when the client application is registered with OP, via the client registration API, a developer console, or some other method.

ClientSecret: Secret value assigned/ generated for the client application on OP.

UserProfileUri: User info endpoint. User will be redirected to this endpoint to change password.

LoginProvider: OP name (ex: KeyCloak).

GetClaimsFromUserInfoEndpoint: Boolean to set whether the handler should go to user info endpoint to retrieve additional claims or not after creating an identity from id_token received from token endpoint. The default value on Admin App is “true”.

Scopes: List of permissions to request.

Defining roles on third party OP:

The users from third party OP should be provided with specific roles for working/ matching with existing Admin App roles.

For more information on Admin App roles. Please refer here.

The role will be added as user attribute on third party OP. Please refer Steps 4 and 6 on Sign in to KeyCloak and configure the environment below.

SuperAdmin – The users who considered SuperAdmin should be provided with edfi_admin_app/super_admin on third party OP.
Admin – The users who considered Admin should be provided with edfi_admin_app/admin on third party OP.
User with no role, will not have access to Global and Settings on Admin App.

Setting up third party OP(KeyCloak):

User can use their own/ existing OpenId Connect provider to delegate authentication process.

We are using KeyCloak as an example here to explain the setup.

Please follow steps below to define client application, users, claims and roles on KeyCloak.

Create and run the infrastructure required:

Create a new Linux VM and install Docker
Start up a KeyCloak container following this guide: https://www.keycloak.org/getting-started/getting-started-docker

You may need to adjust the port mapping based on the setup of the VM or any firewalls (or change that setup to match KeyCloak defaults)
Is it OK to start/use KeyCloak dev mode

or should we install Postgres

?
Using dev mode will give

PT team

access to settings

they

the user may wish to change, but is not recommended for production (for persistence, ssl, etc)

.
We might clarify we're looking to test Admin App's integration with OIDC, not the OIDC provider setup

.

Sign in to KeyCloak and configure the environment:

Create a Realm to manage the Ed-Fi apps from (do not use Master)

Click the Master 🔽 dropdown and click Create New Realm
Call it edfi

Create a new Client for Admin App
- General Settings:
- Capability Config

Make sure you're in the edfi realm
Click Clients in the left sidebar
Click Create Client
Save

Save general Client settings
- Select keycloak theme
- Turn on Front Channel Logout and Backchannel logout session required

Click the adminapp client. On the first tab:
Set Root URL and Home URL to the (full) URL of your Admin App
Set Valid redirect URIs, Valid post logout redirect URIs and Web origins to your-admin-app-url/*
Login Settings:
Logout Settings:
Save

Create mappings to pass claims on to users:
- Name: Admin App Role Mapper
- User Attribute: admin-app-role
- Token claim name: http://schemas\.microsoft\.com/ws/2008/06/identity/claims/role
- Claim JSON type: String
- Enable Add to ID token, Add to access token, Add to userinfo
- Save

Click the Client Scopes tab
Click adminapp-dedicated
Click Add Mapper 🔽 and By configuration
Select User Attribute

Create a user
- Must have Username and Email but values are up to you
- Enable Enabled
- Click Create

Make sure you're in the edfi realm
Click Users in the left sidebar
Click Add user

Set up user info
- Click Attributes
- Add an attribute for their role:
- Save
- Click Credentials
- Click Set Password
- Type in a password
- Enable Temporary (so the user logging in must pick a new one)

Add role information
Add password

Repeat above steps to create the following users:

SuperAdmin
Admin
No Role
(Other case such as "No Email" if needed for testing)

KeyCloak is now configured! Time to update Admin App config.

Copy your client secret

Make sure you're in the edfi realm
Click Clients in the left sidebar
Select adminapp
Click Credentials
Copy the Client secret

Update Admin App Config in the IdentitySettings section:

Type: OpenId
AuthenticationScheme: oidc
Authority: *http://your-keycloak-url:port/realms/edfi*
ClientId: adminapp
ClientSecret: value-you-copied
UserProfileUri: http://your-keycloak-url:port/realms/edfi/protocol/openid-connect/userinfo
LoginProvider: KeyCloak
Leave the rest as-are

Restart Admin App

To verify: launch Admin App and sign in. You should be taken to KeyCloak and be able to sign in using the username and passwords you created.

Singing into Admin App using KeyCloak:

Image Modified

Redirecting to KeyCloak for sign in:

Image Modified

After providing valid credentials and clicking Sign in, user will be navigated to Admin App Home Page and

provided with Global and/or Settings as per their roles.

Super Admin user from KeyCloak:

Image Modified

Admin user from KeyCloak:

Image Modified

No-role user from KeyCloak:

Image Modified

Clicking on SETTINGS will redirect to "Unauthorized" error page.

Image Modified

References:

https://learn.microsoft.com/en-us/aspnet/core/security/authentication/social/?view=aspnetcore-3.1&tabs=visual-studio

https://www.keycloak.org/getting-started/getting-started-docker

Versions Compared

Old Version 18

New Version Current

Key

Overview

Admin App Roles

1. Super-Administrator (default role for the first user)

Super-Administrator Permissions

2. Administrator

Administrator Permissions

Securing Admin App

Web Form Authentication

First-Time Administrative User Setup

First-Time Admin App system setup

Additional User Setup

Single

Sign-On with Open ID Connect (Admin App v3.x+)

Defining roles on third party OP:

Setting up third party OP(KeyCloak):

Singing into Admin App using KeyCloak:

Redirecting to KeyCloak for sign in:

Super Admin user from KeyCloak:

Admin user from KeyCloak:

No-role user from KeyCloak:

Page Comparison

Versions Compared

Old Version 18

New Version Current

Key

Overview

Admin App Roles

1. Super-Administrator (default role for the first user)

Super-Administrator Permissions

2. Administrator

Administrator Permissions

Securing Admin App

Web Form Authentication

First-Time Administrative User Setup

First-Time Admin App system setup

Additional User Setup

Single

Sign-On with Open ID Connect (Admin App v3.x+)

Defining roles on third party OP:

Setting up third party OP(KeyCloak):

Singing into Admin App using KeyCloak:

Redirecting to KeyCloak for sign in:

Super Admin user from KeyCloak:

Admin user from KeyCloak:

No-role user from KeyCloak: