SkillTree Docs

# Installation Modes

The SkillTree dashboard and service (skills-service) support two separate modes of authentication. The dashboard can be configured for password based authentication or PKI based authentication.

  • Password Auth Mode: Accounts created and managed by SkillTree and/or delegated to OAuth2 authentication provider (ex. GitHub, Google, etc..)
  • PKI Auth Mode: PKI Mode is for intranets where organizations utilize PKI with 2-way SSL certificates to implement authentication and authorization. User's browser must be setup with a personal PKI certificate and that certificate must be issued by a Certificate Authority trusted in the dashboard application's truststore.

TIP

Definitely use Password Auth Mode if you are not sure which mode is applicable to you.

# Password Auth Mode

When configured for password based authentication, users will need to manually create a SkillTree account by clicking on the "Sign Up" link on the main login page. After creating an account, users can login using the username and password that was used when creating the account.

Password Auth Mode is enabled by default, or can be explicitly enabled by setting the following property:

skills.authorization.authMode=FORM

# OAuth Support

When using Password Auth Mode, the dashboard can also support OAuth2 based authentication. Currently, OAuth2 is only supported for Google, GitHub, GitLab and Azure Active Directory.
Login buttons get automatically added to the Login page when configured.
To configure, you will need a client ID and client Secret credentials.
These credentials can be created and managed through the providers OAuth Google , GitHub , GitLab , or Azure AD management pages.

Once the client ID and secret are set up, they are enabled by adding the following properties:

# Google
spring.security.oauth2.client.registration.google.client-id=<Google client id here>
spring.security.oauth2.client.registration.google.client-secret=<Google client secret here>
spring.security.oauth2.client.registration.google.redirectUriTemplate='https://<SkillTree Dashboard Host>/{action}/oauth2/code/{registrationId}'
spring.security.oauth2.client.registration.google.iconClass=fab fa-google

# GitHub
spring.security.oauth2.client.registration.github.client-id=<GitHub client id here>
spring.security.oauth2.client.registration.github.client-secret=<GitHub client secret here>
spring.security.oauth2.client.registration.github.redirectUriTemplate='https://<SkillTree Dashboard Host>/{action}/oauth2/code/{registrationId}'
spring.security.oauth2.client.registration.github.iconClass=fab fa-github

# GitLab
spring.security.oauth2.client.registration.gitlab.client-id=<GitLab client id here>
spring.security.oauth2.client.registration.gitlab.client-secret=<GitLab  client secret here>
spring.security.oauth2.client.registration.gitlab.redirect-uri=https://<SkillTree Dashboard URL>/{action}/oauth2/code/{registrationId}
spring.security.oauth2.client.registration.gitlab.authorization-grant-type=authorization_code
spring.security.oauth2.client.registration.gitlab.clientName=GitLab
spring.security.oauth2.client.registration.gitlab.iconClass=fab fa-gitlab
spring.security.oauth2.client.provider.gitlab.authorization-uri=https://gitlab.com/oauth/authorize
spring.security.oauth2.client.provider.gitlab.token-uri=https://gitlab.com/oauth/token
spring.security.oauth2.client.provider.gitlab.user-info-uri=https://gitlab.com/api/v4/user
spring.security.oauth2.client.provider.gitlab.user-name-attribute=username

# Azure AD
spring.security.oauth2.client.registration.azure.client-id=<Azure App Registration client ID>
spring.security.oauth2.client.registration.azure.client-secret=<Azure App Registration client secret>
spring.security.oauth2.client.registration.azure.redirect-uri=https://<SkillTree Dashboard URL>/{action}/oauth2/code/{registrationId}
spring.security.oauth2.client.registration.azure.iconClass=fab fa-microsoft
spring.security.oauth2.client.registration.azure.scope=openid,profile,email
spring.security.oauth2.client.registration.azure.authorization-grant-type=authorization_code
spring.security.oauth2.client.registration.azure.client-name=Azure
spring.security.oauth2.client.registration.azure.provider=azuread
spring.security.oauth2.client.provider.azuread.authorization-uri=https://login.microsoftonline.com/common/oauth2/v2.0/authorize
spring.security.oauth2.client.provider.azuread.token-uri=https://login.microsoftonline.com/common/oauth2/v2.0/token
spring.security.oauth2.client.provider.azuread.user-info-uri=https://graph.microsoft.com/oidc/userinfo
spring.security.oauth2.client.provider.azuread.jwk-set-uri=https://login.microsoftonline.com/common/discovery/keys

Excluding a provider configuration section will prevent the respective OAuth login button from being added to the Login page.

Note: To disable username/password authentication entirely and only support OAuth based authentication, set the following configuration property:

skills.authorization.oAuthOnly=true

# PKI Auth Mode

PKI Mode is for intranets where organizations utilize PKI with 2-way SSL certificates to implement authentication and authorization. When configured for PKI based authentication, the user's browser must be setup with a personal PKI certificate and that certificate must be issued by a Certificate Authority trusted in the dashboard application's truststore.

To enable PKI Auth Mode, set the following configuration property:

skills.authorization.authMode=PKI

PKI Mode requires:

  • running User Info Service
  • configuring client properties to communicate with User Info Service

# User Info Service

In PKI Mode, users authenticate using PKI certificates - the only information that is extracted from a client certificate is the Distinguished Name (DN). The User Info Service provides a way to look up users' metadata by DN, such as name and email. It is your responsibility to implement and run an instance of User Info Service specific to your organization.

The User Info Service is configured in the skills-service by adding the following configuration properties:

# To retrieve user info by DN
skills.authorization.userInfoUri=https://<host>:<port>/userInfo?dn={dn}
# Used by dashboard dropdowns to suggest existing users
skills.authorization.userQueryUri=https://<host>:<port>/userQuery?query={query}
# skills-service checks the health of User Info Service
skills.authorization.userInfoHealthCheckUri=https://<host>:<port>/actuator/health

The User Info Service will need to implement the following REST endpoints that can return user information for the client certificate's Distinguished Name (DN):

  • skills.authorization.userInfoUri
  • skills.authorization.userQueryUri
  • skills.authorization.userInfoHealthCheckUri

# skills.authorization.userInfoUri endpoint

This endpoint returns user information by DN. The endpoint is configured via the skills.authorization.userInfoUri property and expects a DN parameter, for example /userInfo?dn={dn}.
This endpoint must return valid JSON with the following properties for a given user's DN:

{
    "firstName":"<value>",
    "lastFirstName":"<value>",
    "email":"<value>",
    "username":"<value>",
    "userDn":"<value>",
    "usernameForDisplay":"<value>"
}
  • username: property is a user's unique identifier; can be a number formatted as a string, ex. 000001
  • usernameForDisplay: this is how user will be display in the SkillTree dashboard

# skills.authorization.userQueryUri endpoint

This endpoint is used by the SkillTree dashboard dropdowns to suggest existing users.

The endpoint is configured via the skills.authorization.userQueryUri property and expects a query parameter, for example: /userQuery?query={query}. This endpoint must return a list of the above JSON objects for user DN's that meet the query criteria. For example:

[
    {
        "firstName":"<value>",
        "lastFirstName":"<value>",
        "email":"<value>",
        "username":"<value>",
        "userDn":"<value>",
        "usernameForDisplay":"<value>"
    },
    {
        "firstName":"<value>",
        "lastFirstName":"<value>",
        "email":"<value>",
        "username":"<value>",
        "userDn":"<value>",
        "usernameForDisplay":"<value>"
    }
]

# skills.authorization.userInfoHealthCheckUri endpoint

Health check endpoint. The endpoint is configured via the skills.authorization.userInfoHealthCheckUri property and should return the following JSON object:

{"status":"UP"}

# optional 2-way SSL

If your User Info Service is configured to use 2-way SSL then skills-service must add the following client authentication properties (Java System Properties): 

# Keystore
-Djavax.net.ssl.keyStore=/certs/keystore.p12
-Djavax.net.ssl.keyStoreType=PKCS12
-Djavax.net.ssl.keyStorePassword=

# Truststore
-Djavax.net.ssl.trustStore=/certs/truststore.p12
-Djavax.net.ssl.trustStoreType=PKCS12
-Djavax.net.ssl.trustStorePassword=

Last Updated: 11/3/2023, 11:47:32 AM