# Access Control using Scopes and Security Permissions

You can limit your application’s access to only the data it needs by using OAuth 2.0 scopes and an APIs’ security permissions and constraints.

Scopes: Using scopes, you can limit your OAuth 2.0 application’s access to Cornerstone data by picking the APIs and operations it has access to. For example, you may grant an application access to only read employee data.
Security Permissions and Constraints: Certain APIs allow you to further restrict your application’s access using security permissions and constraints. For example, with the Express Class API, you can choose to allow your application to create express class records for users from a specific division or geographical region.

Most APIs require both:

A scope to be assigned to the OAuth 2.0 application and token
And security permissions to be assigned to the user tied to the OAuth 2.0 application.

# Scopes

Scopes allow the authorization server (in this case Cornerstone) to control what resources (APIs) an external application has access to. It limits the "scope" of a token issued by the Cornerstone. Cornerstone enforces scopes in two ways:

Application registration: At the time of registering an application in the Manage Applications page, you will need to select the scopes you want to tie your application to. For example, if you are building an integration between Cornerstone and a Human Resource Information System (HRIS), you will likely only need access to create, update, and read employee data. Hence you would select employee:read, employee:create, employee:updatefull, and employee:updatepartial scopes.
Token acquisition: At the time of acquiring an access token, you will need to pass a space delimited list of scopes (see example below). The scopes you pass in the request must be associated with your OAuth 2.0 application. Extending the above HRIS example, if you are acquiring a token which you will use to fetch employee data from Cornerstone, you should only pass the employee:read scope in the token request. Cornerstone will then issue an access token which only allows you to perform GET operations using the Employee API.

# Token Request with Scopes
curl -X POST \
  http://[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"
  }'

This two-step process allows a client administrator to limit access to specific APIs and operations while registering an OAuth 2.0 application. A developer building the integration would then need to ensure that requests to get an access token include scopes that are within the list of scopes selected by the administrator.

Best Practice

As a best practice, we recommend that you make token requests for the lowest level of access needed to perform your transaction. For example, in the above HRIS scenario, even though your application had access to create, update and read employee data, your token request was only for the employee:read scope.

There are several scenarios that can play out with this two-step process. The table below illustrates these scenarios with examples. The 'OAuth 2.0 Application Scopes' column indicates the scopes selected by an administrator in the Manage Applications page. The 'Scopes in OAuth 2.0 Token Request' column indicates the scopes sent in the request to get an access token.

ID	OAuth 2.0 Application Scopes	Scopes in OAuth 2.0 Token	Request Result
1	All (select all scopes under Cornerstone API and Reporting API)	`all`	Access token issued with `scope = all`
2	All (select all scopes under Cornerstone API and Reporting API)	`employee:read`	Access token issued with `scope = employee:read`
3	All (select all scopes under Cornerstone API and Reporting API)	`employee:read` `employee:create`	Access token issued with `scope = employee:read employee:create`
4	All (select all scopes under Cornerstone API and Reporting API)	`nonsenseScope`	HTTP 400 error because that scope does not exist in Cornerstone
5	employee:read, employee:create	`employee:read`	Access token issued with `scope = employee:read`
6	employee:read, employee:create	`employee:updatefull`	HTTP 400 error because the OAuth 2.0 application does not have the `employee:updatefull` scope
7	employee:read, employee:create	`employee:read` `nonsenseScope`	Access token issued with `scope = employee:read`
8	All scopes under Cornerstone API selected. No scopes selected under Reporting API.	`vw_rpt_training:read`	HTTP 400 error because the OAuth 2.0 application does not have the `vw_rpt_training:read` scope
9	employee:read, employee:create	`all`	Access token issued with `scope = employee:read employee:create`
10	employee:read, employee:create	`employee:read` `employee:create` `employee:updatefull`	Access token issued with `scope = employee:read employee:create`

# Scopes Validation

When Cornerstone's Authorization server receives a request for an API call, it evaluates the scopes associated with the token. If you use a token to access an endpoint that it does not have the 'scope' for, you will see an HTTP 401 error in the response. For example, you cannot use a token which only has the employee:read scope to perform a POST operation since that scope only allows you to perform GET operations on the Employee API.

# Security Permissions and Constraints

Security permissions provide a user access to specific functionality within the system. Constraints limit a user's permission to a specified area. While these permissions and constraints primarily help client administrators to control access to features in the Cornerstone UI, they are also available and in most cases required for accessing Cornerstone's APIs.

For example, if you wish to create an Express Class using the Express Class API, the user account associated with your OAuth 2.0 application must have the 'Express Class - Manage' permission. If you further wish to restrict access to your OAuth 2.0 application so that it's allowed to only create Express Class for employees in a specific division, you would constraint the permission to that division.

In short, 'Permissions' provide access to an API resource and 'Constraints' limit how much of that resource can be accessed.

When an API requires specific permissions, the documentation in the Developer Portal calls it out. screenshot of Developer Portal

Additionally, you can find a consolidated list of API endpoints, associated scopes, and any required permissions on this page: List of Scopes and Security Permissions for APIs

# Create a Security Role

To assign security permissions and constraints to the user account tied to your OAuth 2.0 application, you must first create a security role. Security roles allow system administrators to create a standard grouping of permissions that can be assigned to users, and these roles determine what individual users can access and do within the system. To create a security role, log in to your Cornerstone portal and navigate to Admin > Tools > Core Functions > Security Role Administration > Click 'Create New Role' > Follow the three step process and hit 'Save'.

Once you have created a role, you can assign the role to the user account tied to your OAuth 2.0 application by following these steps:

On the Security Role Administration page, search for the role you just created.
Click on the 'Users' icon for your security role.
Click 'Add Users'.
In the 'Select Criteria' dropdown, select 'Users'. Click on the icon next to the dropdown.
In the resulting pop-up window, search for the user you created in step # 1.
In the search results, click the Add icon next to your user.
Click 'Done' and Click 'Save'.

# Permissions and Constraints Validation

If the user associated with your OAuth 2.0 application does not have the required security permissions or constraints to perform an operation, you will get an HTTP 401 response from Cornerstone. The error message in the response body will indicate that you do not have the required security permissions and/or constraints. If you encounter this error, please review the security permission assigned to the user tied to your OAuth 2.0 application.