Authentication

Cornerstone's APIs use the OAuth 2.0 authorization framework. Currently, Cornerstone only supports OAuth 2.0's Client Credential grant type. If you are not familiar with OAuth 2.0, please click here for a brief overview of this industry standard authentication and authorization framework.

Register an Application

Every application that you intend to integrate using Cornerstone's APIs and OAuth 2.0 must be registered within the API Management page. You can register multiple applications with Cornerstone to get a distinct client ID and secret for each application.

1. Login to your Cornerstone portal.
2. Navigate to Admin > Tools > Edge > API Management.
3. On the Manage Applications tab, click Register New Application.
4. Enter your Application Name.
5. Enter the User ID of an active user in your portal.

TIP

For the client credential grant flow, you must associate each registered application with a user account which will function as a "service account". This user account will be bound to the application created and by extension to the client ID and secret. When your client application makes a call to a Cornerstone API endpoint using the access token issued by Cornerstone, the following steps occur:

1. Cornerstone's authorization server verifies the access token and the registered application for which Cornerstone issued the token.
2. If the access token is valid, the authorization server proceeds to retrieve the user account associated with the application and passes it in the context to the resource (the API).
3. The API verifies this user's security permissions and constraints before returning a response. If the user does not have the required permissions to perform the actions supported by the API, the API will respond with an HTTP 401 Unauthorized error.

6. In the Access Token Validity Period field, enter the period in seconds for which Cornerstone should issue access tokens for this application. Value should be a valid integer between 300 and 86,400. If no value is entered in this field, Cornerstone will issue access tokens that are valid for 3600 seconds by default (1 hour).
7. In the Scopes section, select the scopes you want to associate with your application. In Cornerstone, scopes function like an access control list. They control the API endpoints your application has access to and the HTTP operations (GET, POST, PUT, PATCH) your application can perform against those endpoints. For example, if your application only needs access to create and retrieve learning object data from Cornerstone, you should select 'training:write' and 'training:read'. To select scopes,
   1. Click on the 'Modify' button for one of the API products. Alternatively, you can select the checkbox next to Cornerstone API and Reporting API to grant your application access to all the endpoints under those products.
   2. In the pop-up window, you can see the scope names and the corresponding HTTP operation and endpoints. Search for and select the scopes you want to associate with your application. You can select multiple scopes for each application.
   3. Click on 'Save'
8. Click Register Application.
9. If the User ID entered is valid, the page refreshes and displays a client ID and client secret. Copy both values and add it to your external application or tool.

TIP

Note that for security reasons, Cornerstone will display the client secret only once. If you need to retrieve the client secret for your application again, you will need to regenerate a new client secret by clicking the 'Regenerate' button.

Acquire a Token and Make an API Call

The client credentials flow is typically used for server-to-server integrations where the end user is not involved in the authentication process. Essentially, the application is acting on its own behalf, i.e., the application is also the resource owner. In this flow, an application presents its client ID and secret to the authorization server to receive an access token.

The diagram below illustrates the client credentials flow that Cornerstone supports. Note that here Cornerstone is the authorization server as well as the resource server with the protected resources being the APIs you wish to eventually call. A description of the steps involved in this flow follows this diagram.

1. Your application or tool should make a POST call to the /services/api/oauth2/token endpoint and pass the clientId, clientSecret, grantType, and scope in JSON format within the request body.
   • For grantType, the value should be client_credentials. Cornerstone does not support any other grant type at this time.
   • Include a space-delimited list of scopes in the scopes field. The order of the scopes does not matter. Click (here) [https://csod.dev/guides/supplements/scopes-security-permissions.html] for a list of valid scopes. You can include up to 20 scopes in a single token request. Note that you must have also selected those scopes while registering the application in the API Management page.
     • If you are not familiar with cURL, read this (article) [https://csod.dev/guides/supplements/using-curl.html] to get an overview of this light-weight command line tool.

# Access token request
curl -X POST \
  https://[corpname].csod.com/services/api/oauth2/token \
  -H 'Content-Type: application/json' \
  -H 'cache-control: no-cache' \
  -d '{
    "clientId": "dbq2kjiql2c4",
    "clientSecret": "l4nqwza+7RbK0rrzs16VMeH+5dWEsFjsRSXtQ0MwL+TSSWvZGliUkgUfIenAk0+1Yx0yPtTs+bSmlotR2KCVGA==",
    "grantType": "client_credentials",
    "scope": "employee:read employee:create"
}'

2. The Cornerstone authorization server validates the credentials.
3. If the credentials are invalid, the Cornerstone authorization server returns a HTTP 400 error. The response body contains an error code describing the error. Here's an example of an error response.

# Access token error response
HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
Cache-Control: private
{
    "status": "400",
    "timeStamp": "2019-04-17T22:19:07+0000",
    "error": {
        "errorId": "edbb11f4-5194-4537-b961-25996f5be2a9",
        "message": null,
        "code": "server_error",
        "description": "Server exception. Cannot Generate Token",
        "details": null
    }
}

4. If the credentials are valid, the authorization server returns the access_token along with the token_type (always bearer), token validity duration in seconds, and scope (always all). Here's an example of a successful response.

# Access token successful response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
    "access_token": "ZWRnZQ:sh97VjZWQJ9pvYVqKiapZYDeLjM8pvFrnku8i6ckuTx8QXaSnIkI4rV7MF21LD2A2A5vKXQqSydq7kGIGV2bQA==",
    "expires_in": 3600,
    "scope": "employee:read employee:create",
    "token_type": "Bearer"
}

5. Using the access_token, your application or tool can now make a call to a Cornerstone API (the protected resource). Include the access_token in the HTTP authorization header. Here's an example request to the Cornerstone Employee API:

# API call using token
curl -X GET \
  https://[corpname].csod.com/services/api/x/users/v1/employees/userid-johndoe\
  - H 'Authorization: Bearer ZWRnZQ:95ro4LHj5iy2G3oZXoY/4epBKDl4+y+vLrVVgtZ++EjZjX8hz4bdPyHRdtUSh21uEfmh/y47io+yVFlFqRcwHA==' \
  - H 'cache-control: no-cache'

6. The Cornerstone authorization server validates the access token.
   • If the access_token is invalid, the authorization server returns a HTTP 401 Unauthorized error. For a token to be valid, it must have been issued by Cornerstone and must not have expired.
   • If the access_token is valid, but the token does not have the required scope to access the API endpoint or perform the HTTP operation, the authorization server returns an HTTP 401 error. For example, if you requested a token with the employee:read scope and tried to use that token to create an employee using the Employee API (which is a POST call to /services/api/x/users/v1/employees), you will get an HTTP 401 error.
   • If the access_token and scope are valid, it passes the request to the API (the protected resource). If the API enforces security permissions and/or constraints, it verifies that the user account associated with the OAuth 2.0 application has the required permissions and/or constraints to perform the operation.
     • If it does not, the API will return an HTTP 401 error.
     • If it has the required permissions and/or constraints, the API performs the operation requested, and returns the response to your application.

See also

• Access Control using Scopes and Security Permissions
• List of Scopes and Security Permissions for APIs
• OAuth 2.0 Overview
• Using cURL