Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 10 Next »

DRAFT

Ways to secure Admin App 3.0:

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

Single sign on:

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:

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.

  1. SuperAdmin – The users who considered SuperAdmin should be provided with edfi_admin_app/super_admin on third party OP.
  2. Admin – The users who considered Admin should be provided with edfi_admin_app/admin on third party OP.
  3. 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 use dev mode or should we install Postgres?
      Using dev mode will give PT team access to settings they 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:

  1. 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
  2. Create a new Client for Admin App
    • General Settings:
      • Client ID: adminapp
    • Capability Config
      • Turn on Client authentication and Authorization
      • Select Standard Flow, Direct access grants, and Implicit flow
    • Make sure you're in the edfi realm
    • Click Clients in the left sidebar
    • Click Create Client
    • Save
  3. 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
  4. Create mappings to pass claims on to users:
    • Click the Client Scopes tab
    • Click adminapp-dedicated
    • Click Add Mapper 🔽 and By configuration
    • Select User Attribute
  5. 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
  6. Set up user info
    • Click Attributes
    • Add an attribute for their role:
      • Key: admin-app-role
      • Value: edfi_admin_app/super_admin or edfi_admin_app/admin
    • 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
  7. 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.

  1. 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
  2. Update Admin App Config in the IdentitySettings section:
  3.  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:

Redirecting to KeyCloak for sign in:

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:

Admin user from KeyCloak:

No-role user from KeyCloak:

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


  • No labels