Authentication

Authentication Endpoint

Production based installation will require you to implement an authentication endpoint. The goal of the endpoint is to authorize a specific user so that the skills display and skills reporting can be properly secured.

Why the need for this endpoint?
Rather than using an API to build displays, the SkillTree platform provides fully navigable Ranking and Visualization views that are directly embeddable into a web-based application. These Ranking and Visualization views need a way to authorize a user so only data for that user is loaded and shared in those UI components. To address this issue SkillTree utilizes the OAuth2 protocol to retrieve a temporary client token which is then used to identify that user. This backend Authentication Endpoint completes OAuth2 integration for your project.

To properly secure authentication secrets the following flow is utilized:

1. SkillTree Client Library is loaded in a browser
2. SkillTree Client Library requests a user token from Your App Backend Server.
3. Your App Backend Server uses the project's Client ID and Client Secret to obtain the user's temporary token (on behalf of this user) from the SkillTree backend server. This temporary token is then sent back to the SkillTree client library (running in the browser).
   • Your project's Client ID and Client Secret are never exposed to the user. To ensure the safety of these credentials, they must only to be securely available to your back-end application server
   • Client ID and Client Secret come from the SkillTree dashboard under Project -> Access -> 'Trusted Client Properties'
4. Your JS code then uses the SkillTree Client Library to load Ranking and Visualizations (Skills Display Component) and to report skill events to the SkillTree backend server.
   • To identify the user securely and accurately SkillTree Client Library sends the token obtained in steps 2-3 as an HTTP Header with each request.

Implementing Authentication Endpoint

The authentication endpoint produces a user specific temporary client token by utilizing a project's Client ID and Client Secret (found in the dashboard under Project -> Access -> 'Trusted Client Properties' )

To retrieve a temporary client token skill, the dashboard provides a /oauth/token endpoint and expects the following parameters:

1. Auth Param: Client Id (from skills dashboard)
2. Auth Param: Client Secret (from skills dashboard)
3. Data Variable Asking for client credentials: grant_type=client_credentials (can be hardcoded)
4. Data Variable specifies which user to retrieve credentials for: proxy_user=<user name> (specific to user that client display is being loaded for)

This is an implementation of the OAuth2 protocol to retrieve a temporary client token. To learn more about OAuth2 here are a couple of resources:

• https://auth0.com/docs/protocols/oauth2
• https://oauth.net/2/
• https://www.digitalocean.com/community/tutorials/an-introduction-to-oauth-2

Below are a number of examples of how you could implement an authentication endpoint that will be utilized by the client display.

Spring Boot Example

Here is a working example of a REST endpoint within a Spring Boot application:

    @CrossOrigin()
    @GetMapping("/users/{user}/token")
    public String getUserAuthToken1(@PathVariable String user) {
        // this is the SkillTree dashboard endpoint that will provide your client token
        String serviceTokenUrl = this.dashboardUrl + "/oauth/token";
        // 1. auth param: client id
        String clientId = this.clientId;
        // 2. auth param: client secret
        String clientSecret = this.secret;
        
        MultiValueMap<String, Object> body = new LinkedMultiValueMap<>();
        // 3. Data Variable Asking for client credentials
        body.add("grant_type", "client_credentials");
        // 4. Data Variable specifies which user to retrieve credentials for
        body.add("proxy_user", user);

        RestTemplate oAuthRestTemplate = new RestTemplate();
        oAuthRestTemplate.setInterceptors(Arrays.asList(new BasicAuthenticationInterceptor(clientId, clientSecret)));
        HttpHeaders headers = new HttpHeaders();
        headers.setContentType(MediaType.APPLICATION_FORM_URLENCODED);

        ResponseEntity<String> responseEntity = oAuthRestTemplate.postForEntity(serviceTokenUrl, new HttpEntity<>(body, headers), String.class);
        return responseEntity.getBody();
    }

CURL Example

Here is an example using CURL (please substitute your values of client-id, client-secret, dashboard-url and user-to-proxy-for):

curl client-id:client-secret@dashboard-url/oauth/token -d "grant_type=client_credentials&proxy_user=user-to-proxy-for"